From 31d23b73159e542d8791602afec991b4d3990cdf Mon Sep 17 00:00:00 2001 From: Arthur Dayne Date: Thu, 3 Oct 2019 15:50:45 +0800 Subject: [PATCH] Generate PDF documentation - 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. - Specify openany in extraclassoptions to skip blank pages (oneside is also specified to use the same page layout for even and odd pages) - tocdepth is set to 2 for better PDF TOC - printindex and makeindex are set to empty in latex_elements to avoid an empty "Index" section in PDF - 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: I70100a71114e1d75833e6c783086325baa0e3fd2 --- doc/requirements.txt | 4 ++-- doc/source/conf.py | 28 +++++++++++++++++++--- doc/source/configuration/sample_config.rst | 22 ++++++++++++----- tox.ini | 13 +++++++++- 4 files changed, 55 insertions(+), 12 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 5876deb9..33c1e952 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,11 +2,11 @@ # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. -sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD -sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD +sphinx>=1.8.0,!=2.1.0 # BSD sphinxcontrib-httpdomain>=1.3.0 # BSD sphinxcontrib-pecanwsme>=0.2 # Apache-2.0 sphinxcontrib-seqdiag>=0.8.4 # BSD +sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD reno>=2.5.0 # Apache-2.0 os-api-ref>=1.4.0 # Apache-2.0 openstackdocstheme>=1.20.0 # Apache-2.0 diff --git a/doc/source/conf.py b/doc/source/conf.py index af91a01b..32674821 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,12 +22,12 @@ sys.path.insert(0, os.path.abspath('../..')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.autodoc', - #'sphinx.ext.intersphinx', 'openstackdocstheme', 'oslo_config.sphinxconfiggen', 'oslo_config.sphinxext', 'oslo_policy.sphinxext', 'oslo_policy.sphinxpolicygen', + 'sphinxcontrib.rsvgconverter', ] # autodoc generation is a bit aggressive and a nuisance when doing heavy @@ -85,13 +85,35 @@ htmlhelp_basename = 'cyborgdoc' html_title = 'Cyborg' html_theme = 'openstackdocs' +# -- Options for LaTeX output ------------------------------------------------- + +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. + # openany: Skip blank pages in generated PDFs + 'maxlistdepth': 10, + 'extraclassoptions': 'openany,oneside', + 'preamble': r'\setcounter{tocdepth}{2}', + 'makeindex': '', + 'printindex': '', +} + +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +# Some distros are missing xindy +latex_use_xindy = False + # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass # [howto/manual]). latex_documents = [ ('index', - 'cyborg.tex', - u'cyborg Documentation', + 'doc-cyborg.tex', + u'Cyborg Documentation', u'OpenStack Foundation', 'manual'), ] diff --git a/doc/source/configuration/sample_config.rst b/doc/source/configuration/sample_config.rst index de747357..0e3599ff 100644 --- a/doc/source/configuration/sample_config.rst +++ b/doc/source/configuration/sample_config.rst @@ -2,11 +2,21 @@ Cyborg Configuration Sample =========================== -The following is a sample cyborg configuration for adaptation and use. It is -auto-generated from cyborg when this documentation is built, so if you are -having issues with an option, please compare your version of cyborg with the -version of this documentation. +.. NOTE(acewit): literalinclude of sample config files causes + LaTeX error (TeX capacity exceeded), so they are skipped in PDF version. -The sample configuration can also be downloaded in `file form <../_static/cyborg.conf.sample>`_. +.. only:: latex -.. literalinclude:: ../_static/cyborg.conf.sample + Sample configuration files for all Cyborg services are found in + the online version of this documentation. + +.. only:: html + + The following is a sample cyborg configuration for adaptation and use. It is + auto-generated from cyborg when this documentation is built, so if you are + having issues with an option, please compare your version of cyborg with the + version of this documentation. + + The sample configuration can also be downloaded in `file form <../_static/cyborg.conf.sample>`_. + + .. literalinclude:: ../_static/cyborg.conf.sample diff --git a/tox.ini b/tox.ini index 6b6a8514..b02966b6 100644 --- a/tox.ini +++ b/tox.ini @@ -9,7 +9,9 @@ ignore_basepython_conflict = True [testenv] usedevelop = True -whitelist_externals = rm +whitelist_externals = + rm + make install_command = {[testenv:common-constraints]install_command} basepython = python3 setenv = @@ -78,8 +80,17 @@ ignore-path = .venv,.git,.tox,*cyborg/locale*,*lib/python*,*cyborg.egg*,api-ref/ [testenv:docs] deps = -r{toxinidir}/doc/requirements.txt commands = + rm -rf doc/build/html sphinx-build -W -b html doc/source doc/build/html +[testenv:pdf-docs] +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:releasenotes] deps = -r{toxinidir}/doc/requirements.txt commands = sphinx-build -a -W -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html