Enable HTML doc builds

This repo was not setup for building docs at all, so:
* enables the docs job and fixes tox.ini for it.
* update doc/requirements.txt
* update doc/source/conf.py for using openstackdocstheme

Note that the documents are just skeletons, so we do not publish the
docs yet, just build them.

Consciously turn off PDF builds for now; one step at a time.

Change-Id: I7a5e301bae315f7ed8cf1a140aaf05c424c787e3

.zuul.yaml

@@ -2,11 +2,15 @@
     templates:
       - openstack-python-jobs
       - libec-pyeclib-jobs-arm64
+      - build-openstack-docs-pti
     check:
       jobs:
         - test-release-openstack: &release_overrides
             vars:
               build_wheel: false
+        - openstack-tox-docs: &doc_overrides
+            vars:
+              tox_skip_pdf: true
         - openstack-tox-py35: &py35_overrides
             vars:
               tox_envlist: py35-compilelibs
@@ -25,6 +29,7 @@
     gate:
       jobs:
         - test-release-openstack: *release_overrides
+        - openstack-tox-docs: *doc_overrides
         - openstack-tox-py35: *py35_overrides
         - openstack-tox-py36
         - openstack-tox-py37

doc/requirements.txt

@@ -1 +1,3 @@
-sphinx>=1.1.2,!=1.2.0,!=1.3b1  # BSD
+sphinx>=1.8.0,<2.0.0;python_version=='2.7' # BSD
+sphinx>=1.8.0;python_version>='3.4'  # BSD
+openstackdocstheme>=1.20.0 # Apache-2.0

doc/source/conf.py

@@ -25,14 +25,18 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['openstackdocstheme']
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
+# openstackdocstheme options
+openstack_repository_name = 'openstack/pyeclib'
+openstack_bug_project = 'pyeclib'
+openstack_bug_tag = ''
+
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
@@ -43,14 +47,6 @@ master_doc = 'index'
 project = 'PyECLib'
 copyright = '2019, Kevin Greenan, Tushar Gohad, Kota Tsuyuzaki'
 
-# 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 = '1.6.1'
-# The full version, including alpha/beta/rc tags.
-release = '1.6.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -91,7 +87,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'openstackdocs'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -120,7 +116,7 @@ html_theme = 'default'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -183,7 +179,7 @@ latex_elements = {
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'PyECLib.tex', 'PyECLib Documentation',
+  ('index', 'doc-pyeclib.tex', 'PyECLib Documentation',
    'Kevin Greenan, Tushar Gohad, Kota Tsuyuzaki', 'manual'),
 ]
 

doc/source/index.rst

@@ -1,8 +1,3 @@
-.. PyECLib documentation master file, created by
-   sphinx-quickstart on Thu Aug 11 19:59:50 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to PyECLib's documentation!
 ===================================
 

tox.ini

@@ -31,7 +31,8 @@ commands = {posargs}
 [testenv:docs]
 deps =
   -r{toxinidir}/doc/requirements.txt
-commands = python setup.py build_sphinx
+commands =
+  sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
 
 [flake8]
 # H101: Use TODO(NAME)