Fix docs builds

This is a squash of two commits, which is required to fix two separate
issues on the stable/pike branch.

First:

Fix docs builds

With the new way of generating docs in the gate[1] our autodoc builds
are slightly broken. Put the required dependencies for doc building and
autodoc generation into doc/requirements.txt. We can also now remove
docs-related requirements from test-requirements.txt.

[1] http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html

(cherry picked from commit ba9c1a3bec)

Second:

Fix the doc CI failure

CI job now uses pip >= 10.0.0 to install the package.

In pip >= 10.0.0, if the package name is missing, the command
"pip install -U" returns error, but in pip < 10.0.0 it
just logs warning.

So this patch make sure the package name exists first.

(cherry picked from commit ad10c32a89)

Co-authored-by: wangxiyuan <wangxiyuan@huawei.com>

Change-Id: Ifbd16fe364bb216821125c70bb7d3ab0ac1f10a3

doc/requirements.txt

@@ -0,0 +1,18 @@
+# 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.
+
+# For generating sphinx documentation
+doc8>=0.6.0 # Apache-2.0
+openstackdocstheme>=1.17.0 # Apache-2.0
+reno>=2.5.0 # Apache-2.0
+sphinx>=1.6.2 # BSD
+
+# For autodoc builds
+mock>=2.0.0 # BSD
+oslotest>=1.10.0 # Apache-2.0
+requests-mock>=1.1.0 # Apache-2.0
+testresources>=2.0.0 # Apache-2.0/BSD
+python-memcached>=1.56 # PSF
+WebTest>=2.0.27 # MIT
+oslo.messaging>=5.29.0 # Apache-2.0

test-requirements.txt

@@ -7,14 +7,11 @@ flake8-docstrings==0.2.1.post1 # MIT
 
 coverage!=4.4,>=4.0 # Apache-2.0
 cryptography!=2.0,>=1.6 # BSD/Apache-2.0
-docutils>=0.11 # OSI-Approved Open Source, Public Domain
 fixtures>=3.0.0 # Apache-2.0/BSD
 mock>=2.0 # BSD
-openstackdocstheme>=1.16.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
 reno!=2.3.1,>=1.8.0 # Apache-2.0
 requests-mock>=1.1 # Apache-2.0
-sphinx>=1.6.2 # BSD
 stevedore>=1.20.0 # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD
 testresources>=0.2.4 # Apache-2.0/BSD

tools/tox_install.sh

@@ -26,5 +26,7 @@ pip install -c"$localfile" openstack-requirements
 # install will be constrained and we need to unconstrain it.
 edit-constraints "$localfile" -- "$CLIENT_NAME"
 
-pip install -c"$localfile" -U "$@"
+if [[ -n "$@" ]]; then
+    pip install -c"$localfile" -U "$@"
+fi
 exit $?

tox.ini

@@ -50,10 +50,12 @@ show-source = True
 exclude = .venv,.tox,dist,doc,*egg,build
 
 [testenv:docs]
+deps = -r{toxinidir}/doc/requirements.txt
 commands=
     python setup.py build_sphinx
 
 [testenv:releasenotes]
+deps = -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
 [hacking]