docs: Resolve issues with Sphinx 2.0

There are multiple steps necessary here:

- Switch to openstackdocstheme which, unlike the EOL'd oslosphinx theme,
  supports Sphinx 2.0. This is mostly trivial, though we do need to set
  the 'release' and 'version' options to the empty string since specs,
  like release notes and API docs, are unversioned.
- Require yasfb 0.8.0, which adds support for Sphinx 2.0
- Remove configuration for configuration for the 'autodoc' extension,
  any builder that isn't HTML or LaTeX, or stuff that duplicates
  defaults. All of these were noise that was simply confusing matters.

Change-Id: I111f5e2b0314b35bdde3e00f7615a380734bc2aa

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.
-oslosphinx>=4.7.0 # Apache-2.0
 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
 sphinxcontrib-seqdiag>=0.8.4 # BSD
-yasfb>=0.5.1,!=0.6.0
+openstackdocstheme>=1.19.0 # Apache-2.0
+yasfb>=0.8.0 # BSD

doc/source/conf.py

@@ -9,27 +9,20 @@ import os
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('.'))
 
-# -- General configuration -----------------------------------------------------
+# -- General configuration ----------------------------------------------------
 
-# 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',
-              'oslosphinx',
-              'yasfb',
-              'sphinxcontrib.seqdiag',
-             ]
+# 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.todo',
+    'openstackdocstheme',
+    'yasfb',
+    'sphinxcontrib.seqdiag',
+]
 
 todo_include_todos = True
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
 # The master toctree document.
 master_doc = 'index'
 
@@ -37,30 +30,20 @@ master_doc = 'index'
 project = u'Nova Specs'
 copyright = u'%s, OpenStack Nova Team' % datetime.date.today().year
 
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-add_module_names = False
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-show_authors = False
-
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['nova-specs.']
 
-# -- Options for HTML output ---------------------------------------------------
+version = ''
+release = ''
+
+# -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'nature'
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1"
-html_last_updated_fmt = os.popen(git_cmd).read()
+html_theme = 'openstackdocs'
 
 # If false, no module index is generated.
 html_domain_indices = False
@@ -68,15 +51,20 @@ html_domain_indices = False
 # If false, no index is generated.
 html_use_index = False
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'Nova-Specsdoc'
+
+# -- openstackdocstheme configuration -----------------------------------------
+
+repository_name = 'openstack/nova-specs'
+use_storyboard = False
 
 
-# -- yasfb configuration -------------------------------------------------------
+# -- yasfb configuration ------------------------------------------------------
 
 feed_base_url = 'http://specs.openstack.org/openstack/nova-specs'
 feed_author = 'OpenStack Nova Team'
 
-# -- seqdiag configuration -----------------------------------------------------
+
+# -- seqdiag configuration ----------------------------------------------------
+
 seqdiag_html_image_format = 'SVG'
 seqdiag_antialias = True

doc/source/redirect.py

@@ -5,15 +5,9 @@
 
 import os.path
 
-from sphinx.application import ENV_PICKLE_FILENAME
-from sphinx.util.console import bold
+from sphinx.util import logging
 
-
-def setup(app):
-    from sphinx.application import Sphinx
-    if not isinstance(app, Sphinx):
-        return
-    app.connect('build-finished', emit_redirects)
+LOG = logging.getLogger(__name__)
 
 
 def process_redirect_file(app, path, ent):
@@ -35,7 +29,7 @@ def process_redirect_file(app, path, ent):
 
 
 def emit_redirects(app, exc):
-    app.builder.info(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):
@@ -43,8 +37,12 @@ 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')
+
+
+def setup(app):
+    app.connect('build-finished', emit_redirects)