Generate PDF documentation

This patch adds a new tox job/command for building the pdf
version of documentation.

tox -epdf-docs

In addition to adjusting the infra requirement for PDF build
support, the following changes are made to build a PDF doc

- Download link of config_options, sample config and policy
  files are disabled for PDF doc as relative links do not
  make sense.
- Pre-create the doc/build/pdf/_static directory as a
  workaround because sphinx_feature_classification.support_matrix extension
  is operating under the assumption that the _static directory already exist
  and trying to copy support-matrix.css into it. We need to remove
  this workaround once the problem in the support_matrix extension is fixed.
- Use the toctree_only=True workaround to avoid TOC duplicate links.

Change-Id: Ief8df5f6a5a22b8d0530458ac45f344a72cc3e49
This commit is contained in:
Vishakha Agarwal 2019-07-10 11:14:42 +05:30 committed by Akihiro Motoki
parent 64a0c4d8c3
commit ce4d065f23
5 changed files with 57 additions and 18 deletions

View File

@ -208,23 +208,26 @@ htmlhelp_basename = 'keystonedoc'
# -- Options for LaTeX output ------------------------------------------------- # -- Options for LaTeX output -------------------------------------------------
# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
latex_use_xindy = False
latex_domain_indices = False
latex_elements = { latex_elements = {
# The paper size ('letterpaper' or 'a4paper'). 'makeindex': '',
# 'papersize': 'letterpaper', 'printindex': '',
'preamble': r'\setcounter{tocdepth}{3}',
# The font size ('10pt', '11pt' or '12pt'). 'maxlistdepth': 10,
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
} }
# Grouping the document tree into LaTeX files. List of tuples (source # Grouping the document tree into LaTeX files. List of tuples (source
# start file, target name, title, author, documentclass # start file, target name, title, author, documentclass
# [howto/manual]). # [howto/manual]).
# NOTE(gyee): Specify toctree_only=True for a better document structure of
# the generated PDF file.
latex_documents = [ latex_documents = [
('index', 'keystone.tex', u'Keystone Documentation', ('index', 'doc-keystone.tex', u'Keystone Documentation',
u'OpenStack', 'manual'), u'OpenStack', 'manual', True)
] ]
# The name of an image file (relative to this directory) to place at the top of # The name of an image file (relative to this directory) to place at the top of

View File

@ -8,8 +8,11 @@ Configuration
The Identity service is configured in the ``/etc/keystone/keystone.conf`` file. The Identity service is configured in the ``/etc/keystone/keystone.conf`` file.
The following tables provide a comprehensive list of the Identity The following tables provide a comprehensive list of the Identity
service options. For a sample configuration file, refer to service options.
:doc:`samples/keystone-conf`.
.. only:: html
For a sample configuration file, refer to :doc:`samples/keystone-conf`.
.. show-options:: .. show-options::
:config-file: config-generator/keystone.conf :config-file: config-generator/keystone.conf

View File

@ -8,8 +8,18 @@ This section provides a list of all possible options and
sample files for keystone configuration. sample files for keystone configuration.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
config-options.rst config-options.rst
policy.rst policy.rst
samples/index.rst
.. # NOTE(gyee): 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::
:maxdepth: 2
samples/index.rst

View File

@ -5,8 +5,11 @@ Policy configuration
Configuration Configuration
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
The following is an overview of all available policies in Keystone. For a sample The following is an overview of all available policies in Keystone.
configuration file, refer to :doc:`samples/policy-yaml`.
.. only:: html
For a sample configuration file, refer to :doc:`samples/policy-yaml`.
.. show-policy:: .. show-policy::
:config-file: ../../config-generator/keystone-policy-generator.conf :config-file: ../../config-generator/keystone-policy-generator.conf

20
tox.ini
View File

@ -142,6 +142,26 @@ commands=
bash -c "rm -rf doc/source/api" bash -c "rm -rf doc/source/api"
sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
# FIXME(gyee): we need to pre-create the doc/build/pdf/_static directory as a
# workaround because sphinx_feature_classification.support_matrix extension
# is operating under the assumption that the _static directory already exist
# and trying to copy support-matrix.css into it. We need to remove
# the workaround after this patch has merged:
# https://review.opendev.org/#/c/679860
[testenv:pdf-docs]
basepython = python3
envdir = {toxworkdir}/docs
deps = {[testenv:docs]deps}
whitelist_externals =
make
mkdir
rm
commands =
rm -rf doc/build/pdf
mkdir -p doc/build/pdf/_static
sphinx-build -W -b latex doc/source doc/build/pdf
make -C doc/build/pdf
[testenv:releasenotes] [testenv:releasenotes]
basepython = python3 basepython = python3
deps = -r{toxinidir}/doc/requirements.txt deps = -r{toxinidir}/doc/requirements.txt