Fix and improve the HTML build, add the PDF build

- make it compatible with latest sphinx:
  * update the requirements (sphinx,
    openstackdocstheme as suggested its maintainers, yasfb)
  * update redirect.py by replacing the API which are not available anymore
    (thanks to nova-specs's https://review.opendev.org/648670)
  * following that review, clean and update conf.py;
- improve the structure of the document. Group by top-level sections
  whenever it makes sense (one for each release of Sahara, and one
  for each additional component). This reduces the number of chapter
  and it makes the document more readable;
- add the required pdf-docs tox environment;
- make sure that the docs tox environment only removes the html builds;
- only show the search section when the HTML generator is used (and fix
  its header when it is shown);
- disable the too smart smartquotes option for the latex builder;
- replace the py27 job with a py36 one to run the (few) internal tests.

Story: 2006117
Task: 35496
Change-Id: I9ac4fa81a80ee36af9e5278fc4a0792689c5a10a

.zuul.yaml

@@ -3,7 +3,7 @@
       - openstack-specs-jobs
     check:
       jobs:
-        - openstack-tox-py27
+        - openstack-tox-py36
     gate:
       jobs:
-        - openstack-tox-py27
+        - openstack-tox-py36

doc/requirements.txt

@@ -1,2 +1,3 @@
-openstackdocstheme>=1.16.0 # Apache-2.0
-sphinx>=1.6.2 # BSD
+openstackdocstheme>=1.20.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

doc/source/conf.py

@@ -28,9 +28,7 @@ sys.path.insert(0, os.path.abspath('.'))
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['redirect',
-              'sphinx.ext.autodoc',
               'sphinx.ext.todo',
-              'sphinx.ext.viewcode',
               'openstackdocstheme',
               'yasfb',
              ]
@@ -94,6 +92,10 @@ pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['sahara-specs.']
 
+# Neither version nor release number for specs
+version = ''
+release = ''
+
 # -- Options for man page output ----------------------------------------------
 man_pages = []
 
@@ -131,14 +133,6 @@ bug_tag = 'spec'
 # pixels large.
 #html_favicon = None
 
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-html_last_updated_fmt = '%Y-%m-%d %H:%M'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 
@@ -178,22 +172,11 @@ htmlhelp_basename = 'Sahara-Specsdoc'
 
 # -- 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-specs.tex', u'Sahara Specs',
-   u'OpenStack Sahara Team', 'manual'),
+  ('index', 'doc-sahara-specs.tex', u'Sahara Specs',
+   u'Sahara Team', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -216,6 +199,8 @@ latex_documents = [
 # If false, no module index is generated.
 #latex_domain_indices = True
 
+smartquotes_excludes = {'builders': ['latex']}
+
 # -- Options for Texinfo output ------------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples

doc/source/index.rst

@@ -4,125 +4,56 @@
 Data Processing Service (Sahara) Specifications
 ===============================================
 
-Rocky specs:
+Implemented specs by release:
 
 .. toctree::
    :glob:
-   :maxdepth: 1
+   :maxdepth: 2
 
-   specs/rocky/*
-
-
-Queens specs:
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/queens/*
-
-
-Pike specs:
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/pike/*
-
-
-Ocata specs:
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/ocata/*
-
-
-Newton specs:
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/newton/*
-
-
-Mitaka specs:
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/mitaka/*
-
-
-Liberty specs:
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/liberty/*
-
-
-Kilo specs:
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/kilo/*
-
-
-Juno specs:
-
-.. toctree::
-  :glob:
-  :maxdepth: 1
-
-  specs/juno/*
+   specs/rocky_idx.rst
+   specs/queens_idx.rst
+   specs/pike_idx.rst
+   specs/ocata_idx.rst
+   specs/newton_idx.rst
+   specs/mitaka_idx.rst
+   specs/liberty_idx.rst
+   specs/kilo_idx.rst
+   specs/juno_idx.rst
 
 
 Unimplemented backlog specs:
 
 .. toctree::
- :glob:
- :maxdepth: 1
+   :glob:
+   :maxdepth: 2
 
- specs/backlog/*
+   specs/backlog_idx.rst
 
-
-Sahara client specs:
+Other components:
 
 .. toctree::
- :glob:
- :maxdepth: 1
+   :glob:
+   :maxdepth: 2
 
- specs/saharaclient/*
+   specs/saharaclient_idx.rst
 
 
-Sahara image elements specs:
-
 .. toctree::
- :glob:
- :maxdepth: 1
+   :glob:
+   :maxdepth: 2
 
- specs/sahara-image-elements/*
+   specs/sahara-image-elements_idx.rst
 
 
-Sahara tests specs:
-
 .. toctree::
- :glob:
- :maxdepth: 1
+   :glob:
+   :maxdepth: 2
 
- specs/sahara-tests/*
+   specs/sahara-tests_idx.rst
 
+.. only:: html
 
-==================
-Indices and tables
-==================
+   Indices and tables
+   ==================
 
-* :ref:`search`
+   * :ref:`search`

doc/source/redirect.py

@@ -6,8 +6,9 @@
 # Stolen from openstack/nova-specs
 
 import os.path
+from sphinx.util import logging
 
-from sphinx.util import console
+LOG = logging.getLogger(__name__)
 
 
 def setup(app):
@@ -36,8 +37,7 @@ def process_redirect_file(app, path, ent):
 
 
 def emit_redirects(app, exc):
-    app.builder.info(
-        console.bold('scanning %s for redirects...') % app.builder.srcdir)
+    LOG.info('scanning %s for redirects...', app.builder.srcdir)
 
     def process_directory(path):
         for ent in os.listdir(path):
@@ -45,8 +45,8 @@ def emit_redirects(app, exc):
             if os.path.isdir(p):
                 process_directory(p)
             elif ent == 'redirects':
-                app.builder.info('   found redirects at %s' % p)
+                LOG.info('   found redirects at %s' % p)
                 process_redirect_file(app, path, ent)
 
     process_directory(app.builder.srcdir)
-    app.builder.info('...done')
+    LOG.info('...done')

requirements.txt

@@ -6,5 +6,5 @@ pbr!=2.1.0,>=2.0.0 # Apache-2.0
 
 cmd2<0.9.0
 stestr>=1.0.0 # Apache-2.0
-testtools>=1.4.0 # MIT
-yasfb>=0.5.1
+testtools>=2.2.0 # MIT
+yasfb>=0.8.0

specs/backlog_idx.rst

@@ -1,7 +1,5 @@
-=======
 Backlog
-=======
-
+^^^^^^^
 
 This directory is for specifications that have been approved but not yet
 implemented.  If you are interested in implementing one of these specifications
@@ -14,3 +12,8 @@ all previous assignees in the list of Other Contributors.
 If a specification has been partially implemented, the document in the backlog
 will contain information of what has been completed.
 
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   backlog/*

specs/juno_idx.rst

@@ -0,0 +1,8 @@
+Juno specs
+^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   juno/*

specs/kilo_idx.rst

@@ -0,0 +1,8 @@
+Kilo specs
+^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   kilo/*

specs/liberty_idx.rst

@@ -0,0 +1,8 @@
+Liberty specs
+^^^^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   liberty/*

specs/mitaka_idx.rst

@@ -0,0 +1,8 @@
+Mitaka specs
+^^^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   mitaka/*

specs/newton_idx.rst

@@ -0,0 +1,8 @@
+Newton specs
+^^^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   newton/*

specs/ocata_idx.rst

@@ -0,0 +1,8 @@
+Ocata specs
+^^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   ocata/*

specs/pike_idx.rst

@@ -0,0 +1,8 @@
+Pike specs
+^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   pike/*

specs/queens_idx.rst

@@ -0,0 +1,8 @@
+Queens specs
+^^^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   queens/*

specs/rocky_idx.rst

@@ -0,0 +1,8 @@
+Rocky specs
+^^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   rocky/*

specs/sahara-image-elements_idx.rst

@@ -0,0 +1,8 @@
+Sahara Image Elements
+^^^^^^^^^^^^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   sahara-image-elements/*

specs/sahara-tests_idx.rst

@@ -0,0 +1,8 @@
+Sahara tests
+^^^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   sahara-tests/*

specs/saharaclient_idx.rst

@@ -0,0 +1,8 @@
+Sahara client
+^^^^^^^^^^^^^
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   saharaclient/*

tox.ini

@@ -21,11 +21,22 @@ commands = {posargs}
 basepython = python3
 deps = -r{toxinidir}/doc/requirements.txt
 commands =
-    rm -rf 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:doc8]
 basepython = python3
 deps =