openstack/nova
Code Issues Proposed changes

Merge "doc: Improve PDF document structure"

Browse Source
This commit is contained in:
Zuul 2019-10-08 16:06:39 +00:00 committed by Gerrit Code Review
commit 43248b4c92
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.