convert docs to PTI

This change converts the repo to the new PTI workflow
and modernises the docs by using the OpenStack docs theme.

Change-Id: I5a3706c7cf40ee0c3405131b89f956bf75cae244

doc/requirements.txt

@@ -0,0 +1,2 @@
+sphinx>=1.6.5,!=1.6.6,!=1.6.7 #BSD
+openstackdocstheme>=1.18.1 # Apache-2.0

doc/source/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -12,22 +11,20 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath('../..'))
 # -- 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 = [
     'sphinx.ext.autodoc',
-    'oslo.sphinx'
+    'openstackdocstheme',
 ]
 
-# autodoc generation is a bit aggressive and a nuisance when doing heavy
-# text edit cycles.
-# execute "export SPHINX_DEBUG=1" in your terminal to disable
+# openstackdocstheme options
+repository_name = 'openstack-infra/elastic-recheck'
+use_storyboard = True
+bug_tag = ''
+
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -49,23 +46,8 @@ add_module_names = True
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# -- Options for HTML output --------------------------------------------------
+# -- Options for HTML output ----------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme_path = ["."]
-# html_theme = '_theme'
-# html_static_path = ['static']
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = '%sdoc' % project
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto/manual]).
-latex_documents = [
-    ('index',
-     '%s.tex' % project,
-     u'%s Documentation' % project,
-     u'OpenStack Foundation', 'manual'),
-]
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'openstackdocs'

doc/source/index.rst

@@ -16,17 +16,8 @@ Contents:
    usage
    contributing
 
-.. # NOTE(mriedem): This is where we hide things that we don't want shown in
-   # the top level table of contents. api/autoindex is hidden since it's in
-   # the modindex link below.
-.. toctree::
-   :hidden:
-
-   api/autoindex
-
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`

setup.cfg

@@ -32,11 +32,6 @@ console_scripts =
     elastic-recheck-uncategorized = elastic_recheck.cmd.uncategorized_fails:main
     elastic-recheck-query = elastic_recheck.cmd.query:main
 
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-
 [upload_sphinx]
 upload-dir = doc/build/html
 
@@ -53,7 +48,3 @@ input_file = elastic_recheck/locale/elastic-recheck.pot
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
 output_file = elastic_recheck/locale/elastic-recheck.pot
-
-[pbr]
-autodoc_index_modules = True
-warnerrors = True

test-requirements.txt

@@ -2,8 +2,6 @@ hacking>=0.12.0,!=0.13.0,<0.14
 coverage>=3.6
 fixtures>=3.0.0
 python-subunit
-sphinx>=1.6.5,!=1.6.6,!=1.6.7 #BSD
-oslo.sphinx
 testrepository>=0.0.17
 testscenarios>=0.4
 testtools>=0.9.36,!=1.2.0

tox.ini

@@ -40,7 +40,8 @@ ignore = E123,E125,H233
 exclude=.venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+deps = -r{toxinidir}/doc/requirements.txt
+commands = sphinx-build -b html -W doc/source doc/build/html
 
 [testenv:bindep]
 # Do not install any requirements. We want this to be fast and work even if