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:
parent
872a823d9a
commit
16b9486bf7
@ -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
|
||||||
|
@ -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 -------------------------------------------
|
||||||
|
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -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
13
tox.ini
@ -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.
|
||||||
|
Loading…
Reference in New Issue
Block a user