Docs: Various fixes

Treat warnings as errors when building documents to early spot problems.

Fix api-ref set up:
* Add openstackdocstheme for api-ref building instead of oslosphinx and
  configure it properly.
* Setup api-ref log-a-bug correctly for this project.
* Remove unneeded extra install command

Fix install-guide set up:
* Add tox environment

Fix releasenotes set up:
* Fix conf.py settings to build without errors, remove index, we don't
  need it.

fix docs set up:
* Use Sphinx 1.5 warning-is-error option for normal build_sphinx.
* use oslo sphinx
* Remove wrong static path setting

Change-Id: I07ce9db9fdb526ab4b083c65afa99c38bb508146

api-ref/source/conf.py

@@ -28,11 +28,18 @@ 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.
 
+import openstackdocstheme
+
 extensions = [
     'os_api_ref',
-    'oslosphinx',
 ]
 
+html_theme = 'openstackdocs'
+html_theme_path = [openstackdocstheme.get_html_theme_path()]
+html_theme_options = {
+    "sidebar_mode": "toc",
+}
+
 # The suffix of source filenames.
 source_suffix = '.rst'
 
@@ -86,6 +93,15 @@ show_authors = False
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# Config logABug feature
+# source tree
+giturl = (
+    u'https://git.openstack.org/cgit/openstack/freezer-api/tree/api-ref/source')
+# html_context allows us to pass arbitrary values into the html template
+html_context = {'bug_tag': 'api-ref',
+                'giturl': giturl,
+                'bug_project': 'freezer'}
+
 # -- Options for man page output ----------------------------------------------
 
 # Grouping the document tree for man pages.

doc/source/conf.py

@@ -30,6 +30,7 @@ import os
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'oslosphinx'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -129,7 +130,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']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

releasenotes/source/conf.py

@@ -129,7 +129,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']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -155,7 +155,7 @@ html_static_path = ['_static']
 #html_domain_indices = True
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False

setup.cfg

@@ -38,6 +38,7 @@ packages =
 source-dir = doc/source
 build-dir = doc/build
 all_files = 1
+warning-is-error = 1
 
 [entry_points]
 oslo.config.opts =

test-requirements.txt

@@ -14,6 +14,7 @@ testrepository>=0.0.18 # Apache-2.0/BSD
 testtools>=1.4.0 # MIT
 os-api-ref>=1.0.0 # Apache-2.0
 reno>=1.8.0 # Apache-2.0
+openstackdocstheme>=1.5.0 # Apache-2.0
 
 # Tempest Plugin
 tempest>=14.0.0 # Apache-2.0

tox.ini

@@ -97,15 +97,17 @@ exclude = .venv,.tox,dist,doc,*egg,specs,build
 commands =
   rm -rf api-ref/build
   python setup.py build_sphinx
-  sphinx-build -b html api-ref/source api-ref/build/html
+  sphinx-build -W -b html api-ref/source api-ref/build/html
+  sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html
 
 [testenv:api-ref]
-whitelist_externals = bash
-                      rm
-install_command = pip install -U --force-reinstall {opts} {packages}
+whitelist_externals = rm
 commands =
   rm -rf api-ref/build
-  sphinx-build -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
+  sphinx-build -W -a -E -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
 
 [testenv:releasenotes]
-commands = sphinx-build -a -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+commands = sphinx-build -W -a -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+
+[testenv:install-guide]
+commands = sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html