From 152d5c359c4615efed046a9f310019c18880455e Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Wed, 18 Sep 2019 06:01:51 +0900 Subject: [PATCH] doc: Improve PDF document structure This is a follow-up patch for https://review.opendev.org/676730. In the TOC of the current PDF file [1], most contents related to user and admin guides are located under "For Contributors" section. This is weird. It happens because the latex builder constructs the document tree based on "toctree" directives even though they are marked as "hidden". This commit reorganizes "toctree" per section. The "toctree" directives must be placed at the end of individual sections. Otherwise, content of a last section and content just after "toctree" directive are concatenated into a same section in the rendered LaTeX document. This commit also improves the following as well: * Specify "openany" as "extraclassoptions" to skip blank pages along with "oneside" to use same page style for odd and even pages. * Set "tocdepth" and "secnumdepth" to 3 respectively. "tocdepth" controls the depth of TOC and "secnumdepth" controls the level of numbered sections in TOC. Note that this commit does not reorganize file structure under doc/source. I believe this should be done separately. [1] https://docs.openstack.org/nova/latest/doc-nova.pdf Change-Id: Ie9685e6a4798357d4979aa6b4ff8a03663a9c71c Story: 2006100 Task: 35140 --- doc/source/conf.py | 9 +- doc/source/configuration/index.rst | 24 ++++- doc/source/contributor/index.rst | 64 ++++++++++++- doc/source/index.rst | 148 ++++++++++++----------------- doc/source/reference/index.rst | 43 +++++++++ doc/source/user/index.rst | 4 + 6 files changed, 199 insertions(+), 93 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 79d53cab9309..cd96c37cb27e 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -130,7 +130,14 @@ latex_documents = [ ] # Allow deeper levels of nesting for \begin...\end stanzas -latex_elements = {'maxlistdepth': 10} +latex_elements = { + 'maxlistdepth': 10, + 'extraclassoptions': 'openany,oneside', + 'preamble': r''' +\setcounter{tocdepth}{3} +\setcounter{secnumdepth}{3} +''', +} # Disable use of xindy since that's another binary dependency that's not # available on all platforms diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index b59a63b4bb52..0ae6054066b9 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -22,6 +22,26 @@ Configuration * :doc:`Sample Config File `: A sample config file with inline documentation. +.. # NOTE(mriedem): This is the section where we hide things that we don't + # actually want in the table of contents but sphinx build would fail if + # they aren't in the toctree somewhere. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + config + +.. # NOTE(amotoki): Sample files are only available in HTML document. + # Inline sample files with literalinclude hit LaTeX processing error + # like TeX capacity exceeded and direct links are discouraged in PDF doc. +.. only:: html + + .. toctree:: + :hidden: + + sample-config + Policy ------ @@ -39,10 +59,11 @@ permissions on REST API actions. .. # NOTE(mriedem): This is the section where we hide things that we don't # actually want in the table of contents but sphinx build would fail if # they aren't in the toctree somewhere. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. .. toctree:: :hidden: - config policy .. # NOTE(amotoki): Sample files are only available in HTML document. @@ -53,5 +74,4 @@ permissions on REST API actions. .. toctree:: :hidden: - sample-config sample-policy diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index fb16630e81da..f16eb55d6033 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -14,6 +14,14 @@ Getting Started * :doc:`/contributor/development-environment`: Get your computer setup to contribute +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + how-to-get-involved + development-environment + Nova Process ============ @@ -44,6 +52,17 @@ while keeping users happy and keeping developers productive. * :doc:`/contributor/ptl-guide`: A chronological PTL reference guide +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + project-scope + policies + process + blueprints + ptl-guide + Reviewing ========= @@ -59,6 +78,15 @@ Reviewing * :doc:`/contributor/documentation`: Guidelines for handling documentation contributions +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + releasenotes + code-review + /reference/i18n + documentation Testing ======= @@ -84,6 +112,18 @@ be Python code. All new code needs to be validated somehow. * :doc:`/contributor/testing/eventlet-profiling` +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + testing + testing/libvirt-numa + testing/serial-console + testing/zero-downtime-upgrade + testing/down-cell + testing/eventlet-profiling + The Nova API ============ @@ -101,6 +141,16 @@ changes done to the API, as the impact can be very wide. * :doc:`/contributor/api-ref-guideline`: The guideline to write the API reference. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + api + api-2 + microversions + api-ref-guideline + Nova Major Subsystems ===================== @@ -108,8 +158,14 @@ Major subsystems in nova have different needs. If you are contributing to one of these please read the :ref:`reference guide ` before diving in. -Move operations -~~~~~~~~~~~~~~~ +* Move operations -* :doc:`/contributor/evacuate-vs-rebuild`: Describes the differences between - the often-confused evacuate and rebuild operations. + * :doc:`/contributor/evacuate-vs-rebuild`: Describes the differences between + the often-confused evacuate and rebuild operations. + +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + evacuate-vs-rebuild diff --git a/doc/source/index.rst b/doc/source/index.rst index 998960ec89b7..f2809195a586 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -49,6 +49,13 @@ For End Users As an end user of nova, you'll use nova to create and manage servers with either tools or the API directly. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + user/index + Tools for using Nova -------------------- @@ -101,6 +108,13 @@ Architecture Overview * :doc:`Nova architecture `: An overview of how all the parts in nova fit together. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + user/architecture + Installation ------------ @@ -112,6 +126,8 @@ having installed :keystone-doc:`keystone `, :glance-doc:`glance :placement-doc:`placement `. Ensure that you follow their install guides first. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. .. toctree:: :maxdepth: 2 @@ -141,6 +157,16 @@ the defaults from the :doc:`install guide ` will be sufficient. * :doc:`Running nova-api on wsgi `: Considerations for using a real WSGI container instead of the baked-in eventlet web server. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + user/feature-classification + user/support-matrix + user/cellsv2-layout + user/wsgi + Maintenance ----------- @@ -163,6 +189,18 @@ Once you are running nova, the following information is extremely useful. instances (either via metadata server or config drive) for your specific purposes. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + admin/index + user/flavors + user/upgrade + user/quotas + user/filter-scheduler + admin/vendordata + Reference Material ------------------ @@ -171,98 +209,36 @@ Reference Material * :doc:`Configuration Guide `: Information on configuring the system, including role-based access control policy rules. -For Contributors -================ - -If you are new to Nova, this should help you start to understand what Nova -actually does, and why. - -.. toctree:: - :maxdepth: 1 - - contributor/index - -There are also a number of technical references on both current and future -looking parts of our architecture. These are collected below. - -.. toctree:: - :maxdepth: 1 - - reference/index - - -.. # NOTE(mriedem): This is the section where we hide things that we don't - # actually want in the table of contents but sphinx build would fail if - # they aren't in the toctree somewhere. For example, we hide api/autoindex - # since that's already covered with modindex below. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. .. toctree:: :hidden: - admin/index - admin/configuration/index cli/index configuration/index - contributor/development-environment - contributor/api - contributor/api-2 - contributor/api-ref-guideline - contributor/blueprints - contributor/code-review - contributor/documentation - contributor/evacuate-vs-rebuild.rst - contributor/microversions - contributor/policies.rst - contributor/releasenotes - contributor/testing - contributor/testing/libvirt-numa - contributor/testing/serial-console - contributor/testing/zero-downtime-upgrade - contributor/testing/down-cell - contributor/testing/eventlet-profiling - contributor/how-to-get-involved - contributor/process - contributor/project-scope - contributor/ptl-guide - reference/api-microversion-history.rst - reference/conductor - reference/glossary - reference/gmr - reference/i18n - reference/live-migration - reference/notifications - reference/policy-enforcement - reference/rpc - reference/scheduling - reference/scheduler-evolution - reference/services - reference/stable-api - reference/threading - reference/update-provider-tree - reference/upgrade-checks - reference/vm-states - reference/scheduler-hints-vs-flavor-extra-specs - reference/isolate-aggregates - user/index - user/architecture - user/availability-zones - user/block-device-mapping - user/cells - user/cellsv2-layout - user/certificate-validation - user/feature-classification - user/filter-scheduler - user/flavors - user/manage-ip-addresses - user/quotas - user/support-matrix - user/upgrade - user/wsgi +For Contributors +================ -Search -====== +* :doc:`contributor/index`: If you are new to Nova, this should help you start + to understand what Nova actually does, and why. +* :doc:`reference/index`: There are also a number of technical references on + both current and future looking parts of our architecture. + These are collected here. -* :ref:`Nova document search `: Search the contents of this document. -* `OpenStack wide search `_: Search the wider - set of OpenStack documentation, including forums. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + contributor/index + reference/index + +.. only:: html + + Search + ====== + + * :ref:`Nova document search `: Search the contents of this document. + * `OpenStack wide search `_: Search the wider + set of OpenStack documentation, including forums. diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index b91670b618c1..a92bf73f9097 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -38,12 +38,38 @@ The following is a dive into some of the internals in nova. * :doc:`/reference/isolate-aggregates`: Describes how the placement filter works in nova to isolate groups of hosts. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + rpc + scheduling + scheduler-hints-vs-flavor-extra-specs + live-migration + services + vm-states + threading + notifications + update-provider-tree + upgrade-checks + conductor + isolate-aggregates + api-microversion-history + Debugging ========= * :doc:`/reference/gmr`: Inspired by Amiga, a way to trigger a very comprehensive dump of a running service for deep debugging. +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + gmr + Forward Looking Plans ===================== @@ -62,8 +88,25 @@ these are a great place to start reading up on the current plans. * :doc:`/reference/scheduler-evolution`: Motivation behind the scheduler / placement evolution +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + /user/cells + policy-enforcement + stable-api + scheduler-evolution + Additional Information ====================== * :doc:`/reference/glossary`: A quick reference guide to some of the terms you might encounter working on or using nova. + +.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to + # keep the document structure in the PDF doc. +.. toctree:: + :hidden: + + glossary diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index c6a3c6811415..21d2a265ee7e 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -10,9 +10,13 @@ End user guide launch-instances metadata + manage-ip-addresses certificate-validation resize reboot + availability-zones + block-device-mapping + /reference/api-microversion-history .. todo:: The rest of this document should probably move to the admin guide.