Merge "Generate PDF documentation"

This commit is contained in:
Zuul 2019-09-11 04:49:17 +00:00 committed by Gerrit Code Review
commit 5fca3f7978
5 changed files with 57 additions and 18 deletions

View File

@ -208,23 +208,26 @@ htmlhelp_basename = 'keystonedoc'
# -- 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 = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
'makeindex': '',
'printindex': '',
'preamble': r'\setcounter{tocdepth}{3}',
'maxlistdepth': 10,
}
# Grouping the document tree into LaTeX files. List of tuples (source
# start file, target name, title, author, documentclass
# [howto/manual]).
# NOTE(gyee): Specify toctree_only=True for a better document structure of
# the generated PDF file.
latex_documents = [
('index', 'keystone.tex', u'Keystone Documentation',
u'OpenStack', 'manual'),
('index', 'doc-keystone.tex', u'Keystone Documentation',
u'OpenStack', 'manual', True)
]
# 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 following tables provide a comprehensive list of the Identity
service options. For a sample configuration file, refer to
:doc:`samples/keystone-conf`.
service options.
.. only:: html
For a sample configuration file, refer to :doc:`samples/keystone-conf`.
.. show-options::
: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.
.. toctree::
:maxdepth: 2
:maxdepth: 2
config-options.rst
policy.rst
samples/index.rst
config-options.rst
policy.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
~~~~~~~~~~~~~
The following is an overview of all available policies in Keystone. For a sample
configuration file, refer to :doc:`samples/policy-yaml`.
The following is an overview of all available policies in Keystone.
.. only:: html
For a sample configuration file, refer to :doc:`samples/policy-yaml`.
.. show-policy::
: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"
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]
basepython = python3
deps = -r{toxinidir}/doc/requirements.txt