From d74ca437b4c190094318a7c2bf337f3f5d0dd80b Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Tue, 17 Sep 2019 15:37:52 +0900 Subject: [PATCH] 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 | 4 ++-- doc/source/admin/index.rst | 2 +- doc/source/archive.rst | 17 +++++++++++++++++ doc/source/conf.py | 5 +++++ doc/source/configuration/index.rst | 2 +- doc/source/contributor/contributing.rst | 4 ---- doc/source/contributor/index.rst | 12 ++++-------- doc/source/index.rst | 22 ++-------------------- doc/source/parameters.rst | 2 +- doc/source/readme.rst | 14 +++++++++++++- doc/source/reference/index.rst | 2 +- doc/source/user/index.rst | 2 +- 12 files changed, 48 insertions(+), 40 deletions(-) create mode 100644 doc/source/archive.rst delete mode 100644 doc/source/contributor/contributing.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 10841ba7..d19a00c2 100644 --- a/CONTRIBUTING.rst +++ b/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. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 9fc72f32..766532a9 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -2,4 +2,4 @@ Administrators guide ==================== -Administrators guide of os-ken. +T.B.D. diff --git a/doc/source/archive.rst b/doc/source/archive.rst new file mode 100644 index 00000000..8cd1ec44 --- /dev/null +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py index c6420d9f..c69c490e 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -81,3 +81,8 @@ latex_documents = [ ] latex_use_xindy = False + +latex_elements = { + 'extraclassoptions': 'openany,oneside', + 'preamble': r'\setcounter{tocdepth}{2}', +} diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index 70cb48d8..baf974db 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -2,4 +2,4 @@ Configuration ============= -Configuration of os-ken. +T.B.D. diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst deleted file mode 100644 index 2aa07077..00000000 --- a/doc/source/contributor/contributing.rst +++ /dev/null @@ -1,4 +0,0 @@ -============ -Contributing -============ -.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 036e4494..0cae1b82 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,9 +1,5 @@ -=========================== - Contributor Documentation -=========================== - -.. toctree:: - :maxdepth: 2 - - contributing +========================= +Contributor Documentation +========================= +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index dede4bef..464dc0e8 100644 --- a/doc/source/index.rst +++ b/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` diff --git a/doc/source/parameters.rst b/doc/source/parameters.rst index 71d4f8a4..8d3201ba 100644 --- a/doc/source/parameters.rst +++ b/doc/source/parameters.rst @@ -16,7 +16,7 @@ OpenFlow/openflow controller, please refer to `openflow org `_ . The mailing list is available at -`OpenStack-dev ML `_ +`OpenStack-dev ML `_ Installing OS-Ken Network Operating System diff --git a/doc/source/readme.rst b/doc/source/readme.rst index a6210d3d..c7e71254 100644 --- a/doc/source/readme.rst +++ b/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/ diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index e4d110e6..a2bd2963 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -2,4 +2,4 @@ References ========== -References of os-ken. +T.B.D. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 9168a548..e4aeab38 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -2,4 +2,4 @@ Users guide =========== -Users guide of os-ken. +T.B.D.