Add PDF documentation build

This commit adds a new tox target to build PDF documentation.
It's a community goal[0] to have PDF docs available.

Also some minor fixes are needed for PDF:
- Only show genindex and search for HTML. Theses elements do not make
sense within PDF documents
- Do not include full config sample files. This will not work and
produces a "Dimension too large" error during the latex run.

[0]
https://governance.openstack.org/tc/goals/selected/train/pdf-doc-generation.html

Change-Id: I66b8c47d599c97e66c2ca76faa66204d5e7c9c3b
This commit is contained in:
Thomas Bechtold 2019-08-27 14:23:45 +02:00
parent 7a3fb6b325
commit b1713e6255
6 changed files with 50 additions and 14 deletions

View File

@ -244,7 +244,7 @@ htmlhelp_basename = 'maniladoc'
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
('index', 'Manila.tex', u'Manila Developer Documentation',
('index', 'manila.tex', u'Manila Developer Documentation',
u'Manila contributors', 'manual'),
]
@ -264,3 +264,12 @@ latex_documents = [
# If false, no module index is generated.
# latex_use_modindex = True
latex_domain_indices = False
latex_elements = {
'makeindex': '',
'printindex': '',
'preamble': r'\setcounter{tocdepth}{3}',
'maxlistdepth': 10,
}

View File

@ -9,5 +9,12 @@ in the ``manila.conf`` file are set to default values.
The ``manila.conf`` file contains most of the options needed to configure
the Shared File Systems service.
.. only:: html
.. literalinclude:: ../../../_static/manila.conf.sample
:language: ini
.. only:: latex
See the online version of this documentation for the full config
file example.

View File

@ -5,7 +5,14 @@ Policy configuration
Configuration
~~~~~~~~~~~~~
.. only:: html
The following is an overview of all available policies in Manila.
.. show-policy::
:config-file: etc/manila/manila-policy-generator.conf
.. only:: latex
See the online version of this documentation for the list of available
policies in Manila.

View File

@ -88,6 +88,8 @@ Module Reference
driver_filter_goodness_weigher
share_migration
.. only:: html
Indices and tables
------------------

View File

@ -139,6 +139,8 @@ Contents:
reference/index
.. only:: html
Additional reference
~~~~~~~~~~~~~~~~~~~~

View File

@ -88,6 +88,15 @@ commands =
doc8 --ignore D001 --ignore-path .tox --ignore-path doc/build --ignore-path manila.egg-info -e .txt -e .rst -e .inc
whitelist_externals = rm
[testenv:pdf-docs]
basepython = python3
deps = {[testenv:docs]deps}
whitelist_externals =
make
commands =
sphinx-build -W -b latex doc/source doc/build/pdf
make -C doc/build/pdf
[testenv:bindep]
# Do not install any requirements. We want this to be fast and work even if
# system dependencies are missing, since it's used to tell you what system