PDF documentation build

Also reorganizes the document structure to match both HTML and PDF docs.

Story: 2006100
Task: 35143

Change-Id: Ie3f38e2ecf52e6a6cbd52bb36196e6f589f1ca0f

doc/source/conf.py

@@ -72,6 +72,20 @@ html_theme = 'openstackdocs'
 # robots.txt.
 html_extra_path = ['_extra']
 
+# -- Options for LaTeX output -------------------------------------------------
+
+latex_documents = [
+    ('index', 'doc-python-novaclient.tex', u'python-novaclient Documentation',
+     u'OpenStack Foundation', 'manual'),
+]
+
+latex_elements = {
+    'extraclassoptions': 'openany,oneside',
+    'preamble': r'\setcounter{tocdepth}{4}',
+    'makeindex': '',
+    'printindex': '',
+}
+
 # -- Options for openstackdocstheme -------------------------------------------
 
 repository_name = 'openstack/python-novaclient'

doc/source/contributor/index.rst

@@ -15,3 +15,4 @@ __ https://docs.openstack.org/infra/manual/developers.html#development-workflow
 
    microversions
    testing
+   deprecation-policy

doc/source/index.rst

@@ -3,7 +3,7 @@
 ===========================================
 
 This is a client for OpenStack Nova API. There's a :doc:`Python API
-<reference/api/index>` (the :mod:`novaclient` module), and a :doc:`command-line
+<reference/index>` (the :mod:`novaclient` module), and a :doc:`command-line
 script </user/shell>` (installed as :program:`nova`). Each implements the
 entire OpenStack Nova API.
 
@@ -22,6 +22,6 @@ such as TryStack, HP, or Rackspace, in order to use the nova client.
    :maxdepth: 2
 
    user/index
-   reference/index
    cli/index
+   reference/index
    contributor/index

doc/source/reference/index.rst

@@ -1,8 +1,8 @@
+=========
 Reference
 =========
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 6
 
-   api/index
-   deprecation-policy
+   api/modules

doc/source/user/index.rst

@@ -6,3 +6,4 @@
    :maxdepth: 2
 
    shell
+   python-api

doc/source/user/python-api.rst

@@ -101,9 +101,4 @@ Then call methods on its managers::
 Reference
 ---------
 
-For more information, see the reference:
-
-.. toctree::
-   :maxdepth: 6
-
-   modules
+See :doc:`the module reference </reference/index>`.

doc/source/user/shell.rst

@@ -87,12 +87,4 @@ From there, all shell commands take the form::
 Run :program:`nova help` to get a full list of all possible commands, and run
 :program:`nova help <command>` to get detailed help for that command.
 
-Reference
----------
-
-For more information, see the reference:
-
-.. toctree::
-   :maxdepth: 2
-
-   /cli/nova
+For more information, see :doc:`the command reference </cli/nova>`.

tox.ini

@@ -9,6 +9,7 @@ usedevelop = True
 whitelist_externals =
   find
   rm
+  make
 passenv = ZUUL_CACHE_DIR
           REQUIREMENTS_PIP_LOCATION
 install_command = pip install {opts} {packages}
@@ -44,11 +45,20 @@ deps =
   -r{toxinidir}/requirements.txt
   -r{toxinidir}/doc/requirements.txt
 commands =
-  rm -rf doc/build
+  rm -rf doc/build/html doc/build/doctrees
   sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
   # Test the redirects. This must run after the main docs build
   whereto doc/build/html/.htaccess doc/test/redirect-tests.txt
 
+[testenv:pdf-docs]
+basepython = python3
+envdir = {toxworkdir}/docs
+deps = {[testenv:docs]deps}
+commands =
+  rm -rf doc/build/pdf
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:releasenotes]
 basepython = python3
 deps =