Update docs building

Cleanup doc/requirements to just use what is needed for doc building.
Move reno to doc/requirements, add doc8 to test-requirements.

update tox.ini:
* doc8 should be in pep8 as linter and not docs according to PTI [1]
* Only build main doc in docs environment, CI uses this and we waste
  just time building api-ref as well, there's a separate environment for
  this. This follows PTI [1]
* Do not include requirements file for docs building, it's not needed
  with apidoc.
* Use common deps for all docs build environments.

Cleanup doc/source/conf.py, with the switch to api-doc a lot of settings
are not needed anymore, also the eventlet bug is fixed.

Update openstackdocstheme to 1.20.0 and which allows to remove obsolete
setting of html_last_updated_fmt, project, latex_elements from conf.py.

Add doc8 to lower-constraints to make requirments-check happy.

[1] https://governance.openstack.org/tc/reference/project-testing-interface.html#documentation

Change-Id: If86dd619402495d9d4470b14cb270fcf53db6794

api-ref/source/conf.py

@@ -25,7 +25,6 @@
 # serve to show the default.
 
 import os
-import subprocess
 import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -141,9 +140,6 @@ html_theme_options = {
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 # html_last_updated_fmt = '%b %d, %Y'
-git_cmd = ["git", "log", "--pretty=format:%ad, commit %h", "--date=local",
-           "-n1"]
-html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8')
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.

doc/requirements.txt

@@ -1,14 +1,11 @@
 # 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.18.1 # Apache-2.0
+openstackdocstheme>=1.20.0 # Apache-2.0
 reno>=2.5.0 # Apache-2.0
-doc8>=0.6.0 # Apache-2.0
 sphinx!=1.6.6,!=1.6.7,>=1.6.3,<2.0.0;python_version=='2.7'  # BSD
 sphinx!=1.6.6,!=1.6.7,!=2.1.0,>=1.6.3;python_version>='3.4'  # BSD
-mock>=2.0.0 # BSD
 os-api-ref>=1.4.0 # Apache-2.0
-ddt>=1.0.1 # MIT
-fixtures>=3.0.0 # Apache-2.0/BSD
 sphinxcontrib-apidoc>=0.2.0  # BSD
 sphinx-feature-classification>=0.1.0 # Apache 2.0
+mock>=2.0.0 # BSD

doc/source/conf.py

@@ -19,26 +19,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import eventlet
 import os
 import sys
 
-from cinder import objects
-
-# NOTE(dims): monkey patch subprocess to prevent failures in latest eventlet
-# See https://github.com/eventlet/eventlet/issues/398
-try:
-    eventlet.monkey_patch(subprocess=True)
-except TypeError:
-    pass
-
-# NOTE(geguileo): Sphinx will fail to generate the documentation if we are
-# using decorators from any OVO in cinder.objects, because the OVOs are only
-# added to the cinder.objects namespace when the CLI programs are run.  So we
-# need to run it here as well to avoid failures like:
-#    AttributeError: 'module' object has no attribute 'Volume'
-objects.register_all()
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -105,7 +88,6 @@ master_doc = 'index'
 repository_name = 'openstack/cinder'
 bug_project = 'cinder'
 bug_tag = 'doc'
-project = u'Cinder'
 copyright = u'2010-present, OpenStack Foundation'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -196,7 +178,7 @@ html_extra_path = ['_extra']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-html_last_updated_fmt = '%Y-%m-%d %H:%M'
+# html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.

lower-constraints.txt

@@ -21,6 +21,7 @@ ddt==1.2.1
 debtcollector==1.19.0
 decorator==3.4.0
 defusedxml==0.5.0
+doc8==0.6.0
 docutils==0.14
 dogpile.cache==0.6.5
 dulwich==0.19.0

releasenotes/source/conf.py

@@ -143,7 +143,7 @@ html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-html_last_updated_fmt = '%Y-%m-%d %H:%M'
+# html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -188,17 +188,6 @@ htmlhelp_basename = 'CinderReleaseNotesdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
-}
-
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).

test-requirements.txt

@@ -22,4 +22,4 @@ tempest>=17.1.0 # Apache-2.0
 # bandit is not included in upper-constraints,
 # so we need to pin it here to a known working version
 bandit==1.6.0 # Apache-2.0
-reno>=2.5.0 # Apache-2.0
+doc8>=0.6.0 # Apache-2.0

tox.ini

@@ -35,19 +35,14 @@ passenv = *_proxy *_PROXY
 [testenv:api-ref]
 basepython = python3
 whitelist_externals = rm
-deps =
+deps = {[testenv:docs]deps}
-    -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
-    -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf api-ref/build
   sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html/
 
 [testenv:releasenotes]
 basepython = python3
-deps =
+deps = {[testenv:docs]deps}
-  -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
-  -r{toxinidir}/requirements.txt
-  -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
 [testenv:functional]
@@ -81,6 +76,7 @@ setenv =
 basepython = python3
 commands =
   flake8 {posargs} .
+  doc8
   {toxinidir}/tools/config/check_uptodate.sh
   {toxinidir}/tools/check_exec.py {toxinidir}/cinder {toxinidir}/doc/source/ {toxinidir}/releasenotes/notes
 
@@ -138,14 +134,10 @@ commands = {posargs}
 basepython = python3
 deps =
   -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
-  -r{toxinidir}/requirements.txt
   -r{toxinidir}/doc/requirements.txt
 commands =
-  doc8
   rm -fr doc/build doc/source/contributor/api/ .autogenerated
   sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
-  rm -rf api-ref/build
-  sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html/
 whitelist_externals = rm
 
 [testenv:gendriverlist]