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

1 files changed, 43 insertions, 0 deletions

diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index b91670b618..a92bf73f90 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