diff --git a/doc/source/conf.py b/doc/source/conf.py index 7c3d88cc..b2bb5883 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -27,6 +27,7 @@ extensions = [ 'oslo_config.sphinxconfiggen', 'oslo_policy.sphinxext', 'oslo_policy.sphinxpolicygen', + 'sphinxcontrib.rsvgconverter', ] # openstackdocstheme options @@ -72,16 +73,32 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M' # Output file base name for HTML help builder. htmlhelp_basename = '%sdoc' % project +# -- Options for LaTeX output ------------------------------------------------- + # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass -# [howto/manual]). +# [howto/manual], torctree_only). latex_documents = [ ('index', - '%s.tex' % project, + 'doc-%s.tex' % project, u'%s Documentation' % project, - u'OpenStack Foundation', 'manual'), + u'OpenStack Foundation', 'manual', + # Specify toctree_only=True for a better document structure of + # the generated PDF file. + True), ] +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +latex_use_xindy = False + +latex_domain_indices = False + +latex_elements = { + 'makeindex': '', + 'printindex': '', + 'preamble': r'\setcounter{tocdepth}{3}', +} + # Example configuration for intersphinx: refer to the Python standard library. #intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/source/index.rst b/doc/source/index.rst index bc93a2ea..2f40e526 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -26,6 +26,11 @@ Welcome to neutron-dynamic-routing's documentation! =================================================== +.. NOTE(amotoki): toctree_only=False is specified in latex_documents + in doc/source/conf.py to get a better structure of the PDF doc. + This means the content of this file (index.rst) is NOT rendered + in the generated PDF file. + .. include:: ../../README.rst Contents diff --git a/lower-constraints.txt b/lower-constraints.txt index aa058ebc..00c3c82c 100644 --- a/lower-constraints.txt +++ b/lower-constraints.txt @@ -123,6 +123,7 @@ simplejson==3.5.1 six==1.10.0 snowballstemmer==1.2.1 Sphinx==1.6.5 +sphinxcontrib-svg2pdfconverter==0.1.0 # BSD sphinxcontrib-websupport==1.0.1 SQLAlchemy==1.2.0 sqlalchemy-migrate==0.11.0 diff --git a/test-requirements.txt b/test-requirements.txt index 18e59781..7fbd53c1 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -8,7 +8,9 @@ fixtures>=3.0.0 # Apache-2.0/BSD flake8-import-order==0.12 # LGPLv3 mock>=2.0.0 # BSD python-subunit>=1.0.0 # Apache-2.0/BSD -sphinx!=1.6.6,!=1.6.7,>=1.6.5 # BSD +sphinx!=1.6.6,!=1.6.7,>=1.6.5,<2.0.0;python_version=='2.7' # BSD +sphinx!=1.6.6,!=1.6.7,!=2.1.0,>=1.6.5;python_version>='3.4' # BSD +sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD openstackdocstheme>=1.18.1 # Apache-2.0 oslo.concurrency>=3.26.0 # Apache-2.0 stestr>=1.0.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index d73b9352..e68b2c3a 100644 --- a/tox.ini +++ b/tox.ini @@ -89,6 +89,16 @@ commands = {posargs} basepython = python3 commands = python setup.py build_sphinx +[testenv:pdf-docs] +basepython = python3 +envdir = {toxworkdir}/docs +# deps = {[testenv:docs]deps} +whitelist_externals = + make +commands = + sphinx-build -W -b latex doc/source doc/build/pdf + make -C doc/build/pdf + [flake8] # E125 continuation line does not distinguish itself from next logical line # E126 continuation line over-indented for hanging indent