Repair building guidelines

The recent yasfb is not compatible with ancient sphinx, just bump
both requirements, as well as replace deprecated oslosphinx with
openstackdocstheme (requirements shamelessly copied from ironic-specs).
While we're here, uncap pbr and bump it to 1.0.

Change-Id: Ia78499827a53f5ee0c7a8b0d9951a0e37dedc91b

.zuul.yaml

@@ -3,7 +3,7 @@
       - openstack-specs-jobs
     check:
       jobs:
-        - openstack-tox-py27
+        - openstack-tox-py37
     gate:
       jobs:
-        - openstack-tox-py27
+        - openstack-tox-py37

doc/source/conf.py

@@ -29,7 +29,7 @@ sys.path.insert(0, os.path.abspath('.'))
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.todo',
               'sphinx.ext.viewcode',
-              'oslosphinx',
+              'openstackdocstheme',
               'yasfb',
              ]
 
@@ -98,7 +98,7 @@ man_pages = []
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'nature'
+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

guidelines/consuming-catalog.rst

@@ -158,8 +158,8 @@ top-level ``token`` object. Such as:
 .. code-block:: json
 
   {
-    'token': {
-      'catalog': {}
+    "token": {
+      "catalog": {}
     }
   }
 
@@ -169,8 +169,8 @@ top-level ``access`` object. Such as:
 .. code-block:: json
 
   {
-    'access': {
-      'serviceCatalog': {}
+    "access": {
+      "serviceCatalog": {}
     }
   }
 

requirements.txt

@@ -1,9 +1,9 @@
 # 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.
-pbr>=0.6,!=0.7,<1.0
-oslosphinx>=2.2.0  # Apache-2.0
-sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
+pbr>=1.0
+openstackdocstheme>=1.18.1 # Apache-2.0
+sphinx!=1.6.6,>=1.6.2 # BSD
 stestr>=2.0.0 # Apache-2.0
 testtools>=0.9.36,!=1.2.0
-yasfb>=0.5.1
+yasfb>=0.8.0

tox.ini

@@ -2,8 +2,9 @@
 # Hold back to 1.4, since that's what's in Fedora 20 repos
 # and we don't need anything newer for nova-specs tests
 minversion = 1.4
-envlist = docs,py27
+envlist = docs,py37
 skipsdist = True
+basepython = python3
 
 [testenv]
 usedevelop = True
@@ -13,9 +14,8 @@ deps = -r{toxinidir}/requirements.txt
 commands = stestr run --slowest {posargs}
 
 [testenv:venv]
-basepython = python3
 commands = {posargs}
 
 [testenv:docs]
-basepython = python3
-commands = python setup.py build_sphinx
+commands =
+  sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html