Doc updates: bump theme to 1.20.0, add PDF build

- bump the openstackdocstheme requirement to 1.20.0, the minimum
  recommended version nowadays, and clean the configuration
  by removing the options now provided by the theme;
- add the pdf-docs tox environment according the established guidelines;
- remove a useless extra title (for both builders);
- docs tox environment: clean up only the generated html, not the entire
  build directory;
- disable the too smart smartquotes option for the latex builder;
- improve the title of the latex document.

Story: 2006117
Task: 35495
Change-Id: I353e33db27c8d676398973995960b98d3163aa0d
This commit is contained in:
Luigi Toscano 2019-09-06 16:52:56 +02:00
parent 7d9be6f485
commit ac675141f0
6 changed files with 16 additions and 46 deletions

View File

@ -1,7 +1,7 @@
# 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.18.1 # Apache-2.0
openstackdocstheme>=1.20.0 # Apache-2.0
os-api-ref>=1.4.0 # Apache-2.0
reno>=2.5.0 # Apache-2.0
sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD

View File

@ -18,7 +18,6 @@ extensions = [
repository_name = 'openstack/sahara-plugin-vanilla'
bug_project = '1106'
bug_tag = 'doc'
html_last_updated_fmt = '%Y-%m-%d %H:%M'
openstack_projects = [
'sahara'
@ -37,18 +36,8 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'sahara-plugin-vanilla'
copyright = u'2015, Sahara team'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.0.1'
# The full version, including alpha/beta/rc tags.
release = '0.0.1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
@ -123,10 +112,6 @@ html_theme = 'openstackdocs'
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
html_use_smartypants = False
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
@ -166,21 +151,10 @@ htmlhelp_basename = 'saharavanillaplugin-testsdoc'
# -- 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.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'sahara-plugin-vanilla.tex', u'sahara-plugin-vanilla Documentation',
('index', 'doc-sahara-plugin-vanilla.tex', u'Sahara Vanilla Plugin Documentation',
u'Sahara team', 'manual'),
]
@ -204,6 +178,7 @@ latex_documents = [
# If false, no module index is generated.
#latex_domain_indices = True
smartquotes_excludes = {'builders': ['latex']}
# -- Options for manual page output --------------------------------------------

View File

@ -1,9 +1,6 @@
Vanilla plugin for Sahara
=========================
User Guide
----------
.. toctree::
:maxdepth: 2

View File

@ -65,7 +65,7 @@ msgpack-python==0.5.6
munch==2.3.2
netaddr==0.7.19
netifaces==0.10.9
openstackdocstheme==1.29.0
openstackdocstheme==1.20.0
openstacksdk==0.24.0
os-api-ref==1.6.0
os-client-config==1.31.2

View File

@ -23,7 +23,6 @@ extensions = [
repository_name = 'openstack/sahara-plugin-vanilla'
bug_project = '1106'
bug_tag = 'releasenotes'
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -35,7 +34,6 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'Sahara Vanilla Plugin Release Notes'
copyright = u'2015, Sahara Developers'
# Release do not need a version number in the title, they
@ -140,17 +138,6 @@ htmlhelp_basename = 'SaharaVanillaReleaseNotesdoc'
# -- 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.
# 'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).

13
tox.ini
View File

@ -51,11 +51,22 @@ deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt}
-r{toxinidir}/doc/requirements.txt
commands =
rm -rf doc/html doc/build
rm -rf doc/build/html
sphinx-build -W -b html doc/source doc/build/html
whitelist_externals =
rm
[testenv:pdf-docs]
basepython = python3
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
whitelist_externals =
make
rm
[testenv:releasenotes]
basepython = python3
deps =