Update for new docs PTI

split docs requirements out into doc/requirements.txt and change the
helper tox docs env to be what the gate is going to be running.

As part of doing this, we can re-enable the enforcer code. However, it
doesn't seem to be working, so leave it as info rather than warn for
now.

Set the jobs and the tox env to use python3. The enforcer module wants
to use ifilterfalse/filterfalse which have different names in 2 vs. 3.
There's no reason to NOT run sphinx in python3.

Change-Id: I358db11b130b909084f7a9e8925477e931d87117

.zuul.yaml

@@ -201,11 +201,17 @@
       - osc-tox-unit-tips
     check:
       jobs:
+        - build-openstack-sphinx-docs:
+            vars:
+              sphinx_python: python3
         - openstacksdk-functional-devstack
         - openstacksdk-functional-devstack-magnum:
             voting: false
         - openstacksdk-functional-devstack-python3
     gate:
       jobs:
+        - build-openstack-sphinx-docs:
+            vars:
+              sphinx_python: python3
         - openstacksdk-functional-devstack
         - openstacksdk-functional-devstack-python3

doc/requirements.txt

@@ -0,0 +1,5 @@
+sphinx>=1.6.2 # BSD
+docutils>=0.11 # OSI-Approved Open Source, Public Domain
+openstackdocstheme>=1.17.0 # Apache-2.0
+beautifulsoup4>=4.6.0 # MIT
+reno>=2.5.0 # Apache-2.0

doc/source/enforcer.py

@@ -117,17 +117,20 @@ def build_finished(app, exception):
 
     # TEMPORARY: Ignore the wait_for names when determining what is missing.
     app.info("ENFORCER: Ignoring wait_for_* names...")
-    missing = set(itertools.ifilterfalse(is_ignored, missing))
+    missing = set(itertools.filterfalse(is_ignored, missing))
 
     missing_count = len(missing)
     app.info("ENFORCER: Found %d missing proxy methods "
              "in the output" % missing_count)
 
-    # TODO(shade) Remove the if DEBUG once the build-openstack-sphinx-docs
+    # TODO(shade) This is spewing a bunch of content for missing thing that
-    # has been updated to use sphinx-build.
+    # are not actually missing. Leave it as info rather than warn so that the
-    if DEBUG:
+    # gate doesn't break ... but we should figure out why this is broken and
-        for name in sorted(missing):
+    # fix it.
-            app.info("ENFORCER: %s was not included in the output" % name)
+    # We also need to deal with Proxy subclassing keystoneauth.adapter.Adapter
+    # now - some of the warnings come from Adapter elements.
+    for name in sorted(missing):
+        app.info("ENFORCER: %s was not included in the output" % name)
 
     if app.config.enforcer_warnings_as_errors and missing_count > 0:
         raise EnforcementError(

test-requirements.txt

@@ -3,20 +3,15 @@
 # process, which may cause wedges in the gate later.
 hacking!=0.13.0,<0.14,>=0.12.0 # Apache-2.0
 
-beautifulsoup4>=4.6.0 # MIT
 coverage!=4.4,>=4.0 # Apache-2.0
 doc8>=0.6.0 # Apache-2.0
-docutils>=0.11 # OSI-Approved Open Source, Public Domain
 extras>=1.0.0 # MIT
 fixtures>=3.0.0 # Apache-2.0/BSD
 jsonschema<3.0.0,>=2.6.0 # MIT
 mock>=2.0.0 # BSD
 python-subunit>=1.0.0 # Apache-2.0/BSD
-openstackdocstheme>=1.17.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
-reno>=2.5.0 # Apache-2.0
 requests-mock>=1.1.0 # Apache-2.0
-sphinx>=1.6.2 # BSD
 stestr>=1.0.0 # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD

tox.ini

@@ -30,6 +30,11 @@ commands = stestr --test-path ./openstack/tests/functional run --serial {posargs
            stestr slowest
 
 [testenv:pep8]
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+  -r{toxinidir}/requirements.txt
+  -r{toxinidir}/test-requirements.txt
+  -r{toxinidir}/doc/requirements.txt
 commands =
   doc8 doc/source
   flake8
@@ -60,11 +65,12 @@ passenv = HOME USER
 commands = {toxinidir}/extras/run-ansible-tests.sh -e {envdir} {posargs}
 
 [testenv:docs]
-skip_install = True
+basepython = python3
 deps =
   -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
- -r{toxinidir}/test-requirements.txt
+  -r{toxinidir}/requirements.txt
-commands = sphinx-build -b html doc/source/ doc/build
+  -r{toxinidir}/doc/requirements.txt
+commands = sphinx-build -W -d doc/build/doctrees -b html doc/source/ doc/build/html
 
 [testenv:releasenotes]
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html