PDF documentation build

- 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: 35491
Change-Id: I353e33db27c8d676398973995960b98d3163aa0d

doc/source/conf.py

@@ -72,7 +72,6 @@ pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
-
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -112,10 +111,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 = {}
 
@@ -158,7 +153,7 @@ htmlhelp_basename = 'saharacdhplugin-testsdoc'
 # 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-cdh.tex', u'sahara-plugin-cdh Documentation',
+  ('index', 'doc-sahara-plugin-cdh.tex', u'Sahara CDH Plugin Documentation',
    u'Sahara team', 'manual'),
 ]
 
@@ -182,6 +177,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 @@
 CDH plugin for Sahara
 =====================
 
-User Guide
-----------
-
 .. toctree::
    :maxdepth: 2
 

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 =