Build pdf doc

The is one of community goals that each project could produce a
single PDF file. The pdf should be in the output of openstack-tox-docs
job.

TeX packages are required to build PDF locally, following is recommended:

* inkscape
* texlive-latex-base
* texlive-latex-extra
* texlive-fonts-recommended

More about the goal:
https://governance.openstack.org/tc/goals/train/pdf-doc-generation.html
https://etherpad.openstack.org/p/train-pdf-support-goal
https://etherpad.openstack.org/p/pdf-goal-train-common-problems

Change-Id: Icf1e4b58675b23e82ee6f6d79eb8852436ed55bb
This commit is contained in:
Kaifeng Wang 2019-09-06 11:57:18 +08:00
parent 1f68fb9073
commit 9aab525d45
8 changed files with 43 additions and 16 deletions

View File

@ -7,3 +7,4 @@ sphinx!=1.6.6,!=1.6.7,!=2.1.0,>=1.6.2;python_version>='3.4' # BSD
sphinxcontrib-apidoc>=0.2.0 # BSD
sphinxcontrib-pecanwsme>=0.10.0 # Apache-2.0
sphinxcontrib-seqdiag>=0.8.4 # BSD
sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD

View File

@ -48,11 +48,12 @@ Configuration
Lists all the configuration options currently accessible via the CONF object
for the current process.
.. only:: html
Sample GMR Report
-----------------
Sample GMR Report
-----------------
Below is a sample GMR report generated for ``ironic-api`` service:
Below is a sample GMR report generated for ``ironic-api`` service:
.. include:: report.txt
.. include:: report.txt
:literal:

View File

@ -38,6 +38,7 @@ extensions = ['sphinx.ext.viewcode',
'sphinxcontrib.pecanwsme.rest',
'sphinxcontrib.seqdiag',
'sphinxcontrib.apidoc',
'sphinxcontrib.rsvgconverter',
'oslo_config.sphinxext',
'oslo_config.sphinxconfiggen',
'oslo_policy.sphinxext',
@ -63,8 +64,7 @@ apidoc_excluded_paths = [
apidoc_separate_modules = True
repository_name = 'openstack/ironic'
bug_project = '943'
bug_tag = ''
use_storyboard = True
wsme_protocols = ['restjson']
@ -126,6 +126,7 @@ else:
# Output file base name for HTML help builder.
htmlhelp_basename = 'Ironicdoc'
latex_use_xindy = False
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
@ -133,13 +134,16 @@ htmlhelp_basename = 'Ironicdoc'
latex_documents = [
(
'index',
'Ironic.tex',
'doc-ironic.tex',
u'Ironic Documentation',
u'OpenStack Foundation',
'manual'
),
]
# Allow deeper levels of nesting for \begin...\end stanzas
latex_elements = {'maxlistdepth': 10}
# -- Options for seqdiag ------------------------------------------------------
seqdiag_html_image_format = "SVG"

View File

@ -11,6 +11,15 @@ situation.
:maxdepth: 1
Configuration Options <config>
Sample Config File <sample-config>
Policies <policy>
.. only:: html
Sample files
------------
.. toctree::
:maxdepth: 1
Sample Config File <sample-config>
Sample Policy File <sample-policy>

View File

@ -100,8 +100,10 @@ Release Notes
`Release Notes <https://docs.openstack.org/releasenotes/ironic/>`_
Indices and tables
==================
.. only:: html
* :ref:`genindex`
* :ref:`search`
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`

View File

@ -45,7 +45,7 @@ When used without the Compute service, the operator needs to create a configurat
and provide the file or HTTP URL to the Bare Metal service.
For the format of the configuration drive, Bare Metal service expects a
``gzipped`` and ``base64`` encoded ISO 9660 [*]_ file with a ``config-2``
``gzipped`` and ``base64`` encoded ISO 9660 [#]_ file with a ``config-2``
label. The `openstack baremetal client
<https://docs.openstack.org/python-ironicclient/latest/cli/osc_plugin_cli.html>`_
can generate a configuration drive in the `expected format`_. Just pass a
@ -134,7 +134,7 @@ the configuration drive and mount it, for example::
mount $CONFIG_DEV /mnt/config
.. [*] A configuration drive could also be a data block with a VFAT filesystem
.. [#] A configuration drive could also be a data block with a VFAT filesystem
on it instead of ISO 9660. But it's unlikely that it would be needed
since ISO 9660 is widely supported across operating systems.

View File

@ -63,6 +63,7 @@ Sphinx==1.6.2
sphinxcontrib-httpdomain==1.6.1
sphinxcontrib-pecanwsme==0.10.0
sphinxcontrib-seqdiag==0.8.4
sphinxcontrib-svg2pdfconverter==0.1.0
sphinxcontrib-websupport==1.0.1
SQLAlchemy==1.0.10
sqlalchemy-migrate==0.11.0

View File

@ -88,6 +88,15 @@ deps =
-r{toxinidir}/driver-requirements.txt
commands = sphinx-build -b html -W doc/source doc/build/html
[testenv:pdf-docs]
basepython = python3
whitelist_externals = make
deps = {[testenv:docs]deps}
commands =
sphinx-build -W -b latex doc/source doc/build/pdf
make -C doc/build/pdf
[testenv:api-ref]
basepython = python3
deps =