Browse Source

Add PDF documentation build

Add a new tox target to build PDF documentation in accord
with the community goal [0] to have PDF docs available.

Also, only show genindex and search for HTML.  These elements
do not make sense within PDF documents.

[0] https://governance.openstack.org/tc/goals/selected/train/pdf-doc-generation.html

Change-Id: Ia75423d1efbec65730130eedf169c458b92b0c9f
changes/49/682149/2
Tom Barron 2 years ago
parent
commit
d9a01c0dd7
6 changed files with 87 additions and 13 deletions
  1. +8
    -6
      README.rst
  2. +8
    -0
      bindep.txt
  3. +13
    -0
      doc/requirements.txt
  4. +38
    -3
      doc/source/conf.py
  5. +6
    -4
      doc/source/index.rst
  6. +14
    -0
      tox.ini

+ 8
- 6
README.rst View File

@ -1,3 +1,11 @@
Team and repository tags
------------------------
.. image:: https://governance.openstack.org/tc/badges/manila-ui.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
.. Change things from this point on
=======================================
manila-ui - Manila Management Dashboard
=======================================
@ -7,9 +15,3 @@ manila-ui - Manila Management Dashboard
* Release notes: https://docs.openstack.org/releasenotes/manila-ui/
* Source: https://opendev.org/openstack/manila-ui
* Bugs: https://bugs.launchpad.net/manila-ui
Team and repository tags
------------------------
.. image:: https://governance.openstack.org/tc/badges/manila-ui.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html

+ 8
- 0
bindep.txt View File

@ -4,3 +4,11 @@ xvfb [selenium platform:dpkg]
# already part of xorg-x11-server on openSUSE
xorg-x11-server-Xvfb [selenium platform:redhat]
# Dependency for pdf document generation
latexmk
texlive-xetex
texlive-fonts-recommended
fonts-liberation
inkscape
librsvg2-bin
imagemagick

+ 13
- 0
doc/requirements.txt View File

@ -0,0 +1,13 @@
# The order of packages is significant, because pip processes them in the order
# of appearance. Changing the order has an impact on the overall integration
# process, which may cause wedges in the gate later.
openstackdocstheme>=1.20.0 # Apache-2.0
reno>=2.5.0 # Apache-2.0
doc8>=0.6.0 # Apache-2.0
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,!=2.1.0,>=1.6.2;python_version>='3.4' # BSD
mock>=2.0.0 # BSD
os-api-ref>=1.4.0 # Apache-2.0
ddt>=1.0.1 # MIT
fixtures>=3.0.0 # Apache-2.0/BSD
oslotest>=3.2.0 # Apache-2.0

+ 38
- 3
doc/source/conf.py View File

@ -26,6 +26,7 @@ extensions = [
'sphinx.ext.autodoc',
#'sphinx.ext.intersphinx',
'openstackdocstheme',
'sphinx.ext.imgconverter',
]
# openstackdocstheme options
@ -70,15 +71,49 @@ html_theme_path = [openstackdocstheme.get_html_theme_path()]
# Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project
# Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None}
# -- Options for LaTeX output -------------------------------------------------
# The paper size ('letter' or 'a4').
# latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
# latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
('index',
'%s.tex' % project,
'doc-%s.tex' % project,
u'%s Documentation' % project,
u'OpenStack Foundation', 'manual'),
]
# Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None}
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# Additional stuff for the LaTeX preamble.
# latex_preamble = ''
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_use_modindex = True
latex_domain_indices = False
latex_elements = {
'makeindex': '',
'printindex': '',
'preamble': r'\setcounter{tocdepth}{3}',
'maxlistdepth': 10,
}

+ 6
- 4
doc/source/index.rst View File

@ -19,8 +19,10 @@ Contents
admin/index
contributor/index
Indices and tables
------------------
.. only:: html
* :ref:`genindex`
* :ref:`search`
Indices and tables
------------------
* :ref:`genindex`
* :ref:`search`

+ 14
- 0
tox.ini View File

@ -80,6 +80,20 @@ commands =
rm -rf doc/build
python setup.py build_sphinx
[testenv:pdf-docs]
usedevelop = True
basepython = python3
deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt}
-r{toxinidir}/requirements.txt
-r{toxinidir}/doc/requirements.txt
whitelist_externals =
make
commands =
sphinx-build -W -b latex doc/source doc/build/pdf
make -C doc/build/pdf
[testenv:releasenotes]
basepython = python3
commands = sphinx-build -a -E -W -d releasenotes/build/doctrees \


Loading…
Cancel
Save