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.