openstack/nova
Code Issues Proposed changes

doc: Improve PDF document structure

Browse Source 
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
This commit is contained in:
Akihiro Motoki 2019-09-18 06:01:51 +09:00 committed by Stephen Finucane
parent 66d17645e2
commit 152d5c359c
6 changed files with 199 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/source/conf.py
View File

@ -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

24
doc/source/configuration/index.rst
View File

@ -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

64
doc/source/contributor/index.rst
View File

@ -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
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

148
doc/source/index.rst
View File

@ -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
================
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>`: Search the contents of this document.
* `OpenStack wide search <https://docs.openstack.org>`_: 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>`: Search the contents of this document.
* `OpenStack wide search <https://docs.openstack.org>`_: Search the wider
set of OpenStack documentation, including forums.

43
doc/source/reference/index.rst
View File

@ -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

4
doc/source/user/index.rst
View File

@ -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.