PDF documentation build

- Add a new pdf-docs environment to enable PDF build.
- sphinxcontrib-svg2pdfconverter is used to handle SVG properly.
- maxlistdepth=10 in latex_elements is needed to handle
  deeper levels of nesting.
- Sample config/policy files are skipped in the PDF document
  as inline sample files cause LaTeX error [1] and direct links
  in PDF doc is discouraged. Note that sample-config and sample-policy
  need to be excluded to avoid the LaTeX error [1] and
  :orphan: is specified in those files.

[1] https://github.com/sphinx-doc/sphinx/issues/3099

Change-Id: I3aaea1d15a357f550f529beaa84fb1a1a7748358
This commit is contained in:
Akihiro Motoki 2019-08-16 00:52:14 +09:00
parent 872a823d9a
commit 16b9486bf7
6 changed files with 46 additions and 12 deletions

View File

@ -2,9 +2,10 @@
# of appearance. Changing the order has an impact on the overall integration # of appearance. Changing the order has an impact on the overall integration
# process, which may cause wedges in the gate later. # process, which may cause wedges in the gate later.
sphinx>=1.8.0,<2.0.0;python_version=='2.7' # BSD sphinx>=1.8.0,<2.0.0;python_version=='2.7' # BSD
sphinx>=1.8.0;python_version>='3.4' # BSD sphinx>=1.8.0,!=2.1.0;python_version>='3.4' # BSD
sphinxcontrib-actdiag>=0.8.5 # BSD sphinxcontrib-actdiag>=0.8.5 # BSD
sphinxcontrib-seqdiag>=0.8.4 # BSD sphinxcontrib-seqdiag>=0.8.4 # BSD
sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
sphinx-feature-classification>=0.2.0 # Apache-2.0 sphinx-feature-classification>=0.2.0 # Apache-2.0
os-api-ref>=1.4.0 # Apache-2.0 os-api-ref>=1.4.0 # Apache-2.0
openstackdocstheme>=1.30.0 # Apache-2.0 openstackdocstheme>=1.30.0 # Apache-2.0

View File

@ -43,6 +43,7 @@ extensions = [
'ext.feature_matrix', 'ext.feature_matrix',
'sphinxcontrib.actdiag', 'sphinxcontrib.actdiag',
'sphinxcontrib.seqdiag', 'sphinxcontrib.seqdiag',
'sphinxcontrib.rsvgconverter',
] ]
# openstackdocstheme options # openstackdocstheme options
@ -123,10 +124,12 @@ html_extra_path = ['_extra']
# (source start file, target name, title, author, documentclass # (source start file, target name, title, author, documentclass
# [howto/manual]). # [howto/manual]).
latex_documents = [ latex_documents = [
('index', 'Nova.tex', u'Nova Documentation', ('index', 'doc-nova.tex', u'Nova Documentation',
u'OpenStack Foundation', 'manual'), u'OpenStack Foundation', 'manual'),
] ]
# Allow deeper levels of nesting for \begin...\end stanzas
latex_elements = {'maxlistdepth': 10}
# -- Options for openstackdocstheme ------------------------------------------- # -- Options for openstackdocstheme -------------------------------------------

View File

@ -3,7 +3,10 @@ Configuration Options
===================== =====================
The following is an overview of all available configuration options in Nova. The following is an overview of all available configuration options in Nova.
For a sample configuration file, refer to :doc:`/configuration/sample-config`.
.. only:: html
For a sample configuration file, refer to :doc:`sample-config`.
.. show-options:: .. show-options::
:config-file: etc/nova/nova-config-generator.conf :config-file: etc/nova/nova-config-generator.conf

View File

@ -17,7 +17,9 @@ Configuration
* :doc:`Config Reference <config>`: A complete reference of all * :doc:`Config Reference <config>`: A complete reference of all
configuration options available in the ``nova.conf`` file. configuration options available in the ``nova.conf`` file.
* :doc:`Sample Config File <sample-config>`: A sample config .. only:: html
* :doc:`Sample Config File <sample-config>`: A sample config
file with inline documentation. file with inline documentation.
Policy Policy
@ -29,7 +31,9 @@ permissions on REST API actions.
* :doc:`Policy Reference <policy>`: A complete reference of all * :doc:`Policy Reference <policy>`: A complete reference of all
policy points in nova and what they impact. policy points in nova and what they impact.
* :doc:`Sample Policy File <sample-policy>`: A sample nova .. only:: html
* :doc:`Sample Policy File <sample-policy>`: A sample nova
policy file with inline documentation. policy file with inline documentation.
.. # NOTE(mriedem): This is the section where we hide things that we don't .. # NOTE(mriedem): This is the section where we hide things that we don't
@ -39,6 +43,15 @@ permissions on REST API actions.
:hidden: :hidden:
config config
sample-config
policy policy
.. # 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
sample-policy sample-policy

View File

@ -2,8 +2,11 @@
Nova Policies Nova Policies
============= =============
The following is an overview of all available policies in Nova. For a sample The following is an overview of all available policies in Nova.
configuration file, refer to :doc:`/configuration/sample-policy`.
.. only:: html
For a sample configuration file, refer to :doc:`sample-policy`.
.. show-policy:: .. show-policy::
:config-file: etc/nova/nova-policy-generator.conf :config-file: etc/nova/nova-policy-generator.conf

13
tox.ini
View File

@ -14,6 +14,7 @@ whitelist_externals =
find find
rm rm
env env
make
install_command = pip install -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} {opts} {packages} install_command = pip install -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} {opts} {packages}
setenv = setenv =
VIRTUAL_ENV={envdir} VIRTUAL_ENV={envdir}
@ -167,7 +168,7 @@ description =
Build main documentation. Build main documentation.
deps = -r{toxinidir}/doc/requirements.txt deps = -r{toxinidir}/doc/requirements.txt
commands = commands =
rm -rf doc/build rm -rf doc/build/html doc/build/doctrees
# Check that all JSON files don't have \r\n in line. # Check that all JSON files don't have \r\n in line.
bash -c "! find doc/ -type f -name *.json | xargs grep -U -n $'\r'" bash -c "! find doc/ -type f -name *.json | xargs grep -U -n $'\r'"
# Check that all included JSON files are valid JSON # Check that all included JSON files are valid JSON
@ -176,6 +177,16 @@ commands =
# Test the redirects. This must run after the main docs build # Test the redirects. This must run after the main docs build
whereto doc/build/html/.htaccess doc/test/redirect-tests.txt whereto doc/build/html/.htaccess doc/test/redirect-tests.txt
[testenv:pdf-docs]
description =
Build PDF documentation.
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:api-guide] [testenv:api-guide]
description = description =
Generate the API guide. Called from CI scripts to test and publish to docs.openstack.org. Generate the API guide. Called from CI scripts to test and publish to docs.openstack.org.