doc: Improve the document structure

This commit updates the document structure to fix
both HTML and PDF versions.
Some minor fixes are also included.

* doc/source/conf.py: Specify openany and oneside
  as extra class options for LaTeX.
* doc/source/conf.py: Specify the depth of TOC for PDF.
* Create a separate top page for "Archived Contents"
* Adjust the content of doc/source/contributor/index.rst
  to avoid unnecessary subsection.
* Drop strings from the top page as they leads to
  separate pages in the PDF file.
* Add "T.B.D." comments to placeholder documents.
* CONTRIBUTING.rst: Remove unnecessary markups for quoting texts.
* doc/source/parameters.rst: Update the mailing list link.

Story: 2006099
Task: 35137
Change-Id: I5fc03cd8ba53df58ee75e1c1bac4e906f840ec4e

CONTRIBUTING.rst

@@ -1,14 +1,14 @@
 If you would like to contribute to the development of OpenStack, you must
 follow the steps in this page:
 
-   http://docs.openstack.org/infra/manual/developers.html
+https://docs.openstack.org/infra/manual/developers.html
 
 If you already have a good understanding of how the system works and your
 OpenStack accounts are set up, you can skip to the development workflow
 section of this documentation to learn how changes to OpenStack should be
 submitted for review via the Gerrit tool:
 
-   http://docs.openstack.org/infra/manual/developers.html#development-workflow
+https://docs.openstack.org/infra/manual/developers.html#development-workflow
 
 Pull requests submitted through GitHub will be ignored.
 

doc/source/admin/index.rst

@@ -2,4 +2,4 @@
 Administrators guide
 ====================
 
-Administrators guide of os-ken.
+T.B.D.

doc/source/archive.rst

@@ -0,0 +1,17 @@
+=================
+Archived Contents
+=================
+
+.. note::
+
+   Contents here are imported from the upstream Ryu documentation.
+   They will be merged into the OS-Ken documentation gradually.
+
+.. toctree::
+   :maxdepth: 2
+
+   developing.rst
+   configuration.rst
+   tests.rst
+   snort_integrate.rst
+   app.rst

doc/source/conf.py

@@ -81,3 +81,8 @@ latex_documents = [
 ]
 
 latex_use_xindy = False
+
+latex_elements = {
+    'extraclassoptions': 'openany,oneside',
+    'preamble': r'\setcounter{tocdepth}{2}',
+}

doc/source/configuration/index.rst

@@ -2,4 +2,4 @@
 Configuration
 =============
 
-Configuration of os-ken.
+T.B.D.

doc/source/contributor/contributing.rst

@@ -1,4 +0,0 @@
-============
-Contributing
-============
-.. include:: ../../../CONTRIBUTING.rst

doc/source/contributor/index.rst

@@ -1,9 +1,5 @@
-===========================
- Contributor Documentation
-===========================
-
-.. toctree::
-   :maxdepth: 2
-
-   contributing
+=========================
+Contributor Documentation
+=========================
 
+.. include:: ../../../CONTRIBUTING.rst

doc/source/index.rst

@@ -7,8 +7,6 @@
 Welcome to the documentation of os_ken
 ======================================
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
@@ -19,27 +17,11 @@ Contents:
    user/index
    admin/index
    reference/index
-
-Archived Contents:
-
-.. note::
-
-   Contents here are imported from the upstream Ryu documentation.
-   They will be merged into the OS-Ken documentation gradually.
-
-.. toctree::
-   :maxdepth: 2
-
-   developing.rst
-   configuration.rst
-   tests.rst
-   snort_integrate.rst
-   app.rst
+   archive
 
 .. only:: html
 
-   Indices and tables
-   ==================
+   .. rubric:: Indices and tables
 
    * :ref:`genindex`
    * :ref:`modindex`

doc/source/parameters.rst

@@ -16,7 +16,7 @@ OpenFlow/openflow controller,
 please refer to `openflow org <http://www.openflow.org/>`_ .
 
 The mailing list is available at
-`OpenStack-dev ML <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>`_
+`OpenStack-dev ML <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss>`_
 
 
 Installing OS-Ken Network Operating System

doc/source/readme.rst

@@ -1 +1,13 @@
-.. include:: ../../README.rst
+========
+Overview
+========
+
+A component-based software defined networking framework in OpenStack.
+
+os-ken is a fork of the Ryu library tailored for OpenStack Neutron.
+
+* License: Apache License, Version 2.0
+* Documentation: https://docs.openstack.org/os-ken/latest/
+* Source: https://opendev.org/openstack/os-ken/
+* Bugs: https://storyboard.openstack.org/#!/project/openstack/os-ken
+* Release Notes: https://docs.openstack.org/releasenotes/os-ken/

doc/source/reference/index.rst

@@ -2,4 +2,4 @@
 References
 ==========
 
-References of os-ken.
+T.B.D.

doc/source/user/index.rst

@@ -2,4 +2,4 @@
 Users guide
 ===========
 
-Users guide of os-ken.
+T.B.D.