Merge "doc: Improve PDF document structure"

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

doc/source/configuration/index.rst

@@ -22,6 +22,26 @@ Configuration
    * :doc:`Sample Config File <sample-config>`: 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

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 <reference-internals>` before
 diving in.
 
-Move operations
+* Move operations
-~~~~~~~~~~~~~~~
 
-* :doc:`/contributor/evacuate-vs-rebuild`: Describes the differences between
+  * :doc:`/contributor/evacuate-vs-rebuild`: Describes the differences between
-  the often-confused evacuate and rebuild operations.
+    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

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 </user/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 <install/>`, :glance-doc:`glance
 :placement-doc:`placement <install/>`. 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 </install/index>` will be sufficient.
 * :doc:`Running nova-api on wsgi <user/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 <configuration/index>`: Information on configuring
   the system, including role-based access control policy rules.
 
-For Contributors
+.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to
-================
+   # keep the document structure in the PDF doc.
-
-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.
 .. 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>`: Search the contents of this document.
+.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to
-* `OpenStack wide search <https://docs.openstack.org>`_: Search the wider
+   # keep the document structure in the PDF doc.
-  set of OpenStack documentation, including forums.
+.. toctree::
+   :hidden:
 
+   contributor/index
+   reference/index
+
+.. only:: html
+
+   Search
+   ======
+
+   * :ref:`Nova document search <search>`: Search the contents of this document.
+   * `OpenStack wide search <https://docs.openstack.org>`_: Search the wider
+     set of OpenStack documentation, including forums.

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

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.