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

doc/requirements.txt

@@ -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

doc/source/conf.py

@@ -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 --------------------------------------------
 

doc/source/index.rst

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

lower-constraints.txt

@@ -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

releasenotes/source/conf.py

@@ -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]).

tox.ini

@@ -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 =