Fix sphinx warnings

Ensure pbr 2.0, which includes a number of bugfixes along with support
for Sphinx 1.5's 'warning-is-error' option is used. Then suppress
"WARNING: nonlocal image URI found" - which gets triggered by our
inclusion of badges in the README.

Change-Id: I1901ec7d19f4d13ef6c8b814243786fb23e70b78
Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>

doc/source/conf.py

@@ -35,6 +35,9 @@ extensions = ['sphinx.ext.autodoc',
               'yasfb',
              ]
 
+# Allow badges in README
+suppress_warnings = ['image.nonlocal_uri']
+
 # Feed configuration for yasfb
 feed_base_url = 'http://specs.openstack.org/openstack/docs-specs'
 feed_author = 'OpenStack Documentation Team'
@@ -98,9 +101,6 @@ modindex_common_prefix = ['docs-specs.']
 # Do not warn about non-local image URI
 suppress_warnings = ['image.nonlocal_uri']
 
-# -- Options for man page output ----------------------------------------------
-man_pages = []
-
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

requirements.txt

@@ -2,8 +2,6 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 
-pbr>=2.0.0 # Apache-2.0
-
 doc8 # Apache-2.0
 oslosphinx>=4.7.0 # Apache-2.0
 sphinx>=1.5.1 # BSD

setup.cfg

@@ -18,6 +18,7 @@ classifier =
     Programming Language :: Python :: 3.4
 
 [build_sphinx]
+builders = html
 all_files = 1
 build-dir = doc/build
 source-dir = doc/source

setup.py

@@ -25,5 +25,5 @@ except ImportError:
     pass
 
 setuptools.setup(
-    setup_requires=['pbr>=1.8'],
+    setup_requires=['pbr>=2.0'],
     pbr=True)

tox.ini

@@ -13,9 +13,15 @@ install_command = pip install -U {opts} {packages}
 commands = doc8 -e .rst specs/ doc/ README.rst
 
 [testenv:venv]
+# NOTE(stephenfin): Use Python 2.7 due to same issue 'docs' env because the
+# gate builds docs this way
+basepython = python2.7
 commands = {posargs}
 
 [testenv:docs]
+# NOTE(stephenfin): Use Python 2.7 until 'yasfb' is Python 3 compliant or is
+# removed -- https://github.com/dhellmann/yasfb/issues/1
+basepython = python2.7
 commands =
   doc8 -e .rst specs/ doc/ README.rst
   sphinx-build -W -b html doc/source doc/build