Update the doc generation (tox, remove warnings PTI)

- isolate the doc requirements into doc/requirements.txt
  according the guidelines of the Project Testing Interface:
  https://governance.openstack.org/tc/reference/project-testing-interface.html#documentation
  http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html
  The upper-requirements.txt file is not used because
  sahara-tests is branchless.
- consistently remove the old builds before calling sphinx:
  implement it for releasenotes,
  simplify the list of directories removed for docs;
- enable warning-as-error for releasenotes and
  fix the only warning found (with a workaround,
  for some reason adding releasenotes.rst to exclude_patterns
  in conf.py did not work).

Change-Id: If0601c5e893853518cd6eb769da2be3037364dc9

doc/requirements.txt

@@ -0,0 +1,7 @@
+# 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.
+
+openstackdocstheme>=1.11.0 # Apache-2.0
+reno!=2.3.1,>=1.8.0 # Apache-2.0
+sphinx>=1.6.2 # BSD

doc/source/releasenotes.rst

@@ -1,3 +1,9 @@
+:orphan:
+
+.. The :orphan: directive is required because
+   this file is not in the toctree
+   even if it is included by a :doc: directive.
+
 =============
 Release Notes
 =============

setup.cfg

@@ -38,3 +38,4 @@ tempest.test_plugins =
 all_files = 1
 build-dir = doc/build
 source-dir = doc/source
+warnings-is-error = 1

test-requirements.txt

@@ -8,7 +8,4 @@ bashate>=0.2 # Apache-2.0
 coverage>=3.6 # Apache-2.0
 doc8 # Apache-2.0
 mock>=1.2 # BSD
-openstackdocstheme>=1.11.0 # Apache-2.0
 pylint==1.4.5 # GNU GPL v2
-reno!=2.3.1,>=1.8.0 # Apache-2.0
-sphinx>=1.6.2 # BSD

tox.ini

@@ -26,10 +26,11 @@ setenv =
 commands = {toxinidir}/tools/cover.sh {posargs}
 
 [testenv:docs]
+deps =
+    -r{toxinidir}/doc/requirements.txt
 commands =
-    rm -rf doc/html doc/build
-    rm -rf doc/source/apidoc doc/source/api
-    python setup.py build_sphinx
+    rm -rf doc/build
+    sphinx-build -W -b html doc/source doc/build/html
 whitelist_externals =
     rm
 
@@ -41,6 +42,10 @@ setenv = VIRTUAL_ENV={envdir}
 commands = bash tools/lintstack.sh
 
 [testenv:pep8]
+deps =
+    -r{toxinidir}/requirements.txt
+    -r{toxinidir}/doc/requirements.txt
+    -r{toxinidir}/test-requirements.txt
 commands =
     flake8 {posargs}
     doc8 doc/source
@@ -52,7 +57,13 @@ commands =
 whitelist_externals = bash
 
 [testenv:releasenotes]
-commands = sphinx-build -a -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+deps =
+    -r{toxinidir}/doc/requirements.txt
+commands =
+    rm -rf releasenotes/build
+    sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+whitelist_externals =
+    rm
 
 [flake8]
 show-source = true