Add doc linting to pep8 target

This adds doc8 to the pep8 job to lint the docs. Also fixes a few issues
it highlighted.

Change-Id: Id0f4b9bee1f6a0103ec581b20037a9b74201aaca
Signed-off-by: Sean McGinnis <sean.mcginnis@gmail.com>

HACKING.rst

@@ -10,7 +10,8 @@ Cinder Client Specific Commandments
 
 General
 -------
-- Use 'raise' instead of 'raise e' to preserve original traceback or exception being reraised::
+- Use 'raise' instead of 'raise e' to preserve original traceback or exception
+  being reraised::
 
     except Exception as e:
         ...
@@ -22,26 +23,28 @@ General
 
 Release Notes
 -------------
-- Any patch that makes a change significant to the end consumer or deployer of an
+- Any patch that makes a change significant to the end consumer or deployer of
-  OpenStack environment should include a release note (new features, upgrade impacts,
+  an OpenStack environment should include a release note (new features, upgrade
-  deprecated functionality, significant bug fixes, etc.)
+  impacts, deprecated functionality, significant bug fixes, etc.)
 
-- Cinder Client uses Reno for release notes management. See the `Reno Documentation`_
+- Cinder Client uses Reno for release notes management. See the `Reno
-  for more details on its usage.
+  Documentation`_ for more details on its usage.
 
 .. _Reno Documentation: https://docs.openstack.org/reno/latest/
 
-- As a quick example, when adding a new shell command for Awesome Storage Feature, one
+- As a quick example, when adding a new shell command for Awesome Storage
-  could perform the following steps to include a release note for the new feature:
+  Feature, one could perform the following steps to include a release note for
+  the new feature::
 
     $ tox -e venv -- reno new add-awesome-command
     $ vi releasenotes/notes/add-awesome-command-bb8bb8bb8bb8bb81.yaml
 
-  Remove the extra template text from the release note and update the details so it
+  Remove the extra template text from the release note and update the details
-  looks something like:
+  so it looks something like::
 
     ---
     features:
       - Added shell command `cinder be-awesome`  for Awesome Storage Feature.
 
-- Include the generated release notes file when submitting your patch for review.
+- Include the generated release notes file when submitting your patch for
+  review.

doc/source/contributor/functional_tests.rst

@@ -40,7 +40,9 @@ For more information on these options and how to run tests, please see the
 Gotchas
 -------
 
-The cinderclient.tests.functional.test_cli.CinderBackupTests.test_backup_create_and_delete
+The cinderclient.tests.functional.test_cli.CinderBackupTests.test_backup_create
-test will fail in Devstack without c-bak service running, which requires Swift.
+and_delete test will fail in Devstack without c-bak service running, which
-Make sure Swift is enabled when you stack.sh by putting this in local.conf :
+requires Swift. Make sure Swift is enabled when you stack.sh by putting this in
-enable_service s-proxy s-object s-container s-account
+local.conf::
+
+    enable_service s-proxy s-object s-container s-account

doc/source/index.rst

@@ -221,6 +221,11 @@ The following are kept for historical purposes.
 * Use Adapter from keystoneclient
 * Add support for Replication feature
 * Add pagination for Volume List
+* Note Connection refused --> Connection error commit:
+  c9e7818f3f90ce761ad8ccd09181c705880a4266
+* Note Mask Passwords in log output commit:
+  80582f2b860b2dadef7ae07bdbd8395bf03848b1
+
 
 .. _1325773: http://bugs.launchpad.net/python-cinderclient/+bug/1325773
 .. _1333257: http://bugs.launchpad.net/python-cinderclient/+bug/1333257
@@ -234,9 +239,6 @@ The following are kept for historical purposes.
 .. _1130572: http://bugs.launchpad.net/python-cinderclient/+bug/1130572
 .. _1156994: http://bugs.launchpad.net/python-cinderclient/+bug/1156994
 
-** Note Connection refused --> Connection error commit: c9e7818f3f90ce761ad8ccd09181c705880a4266
-** Note Mask Passwords in log output commit: 80582f2b860b2dadef7ae07bdbd8395bf03848b1
-
 1.0.9
 ------
 

lower-constraints.txt

@@ -6,6 +6,7 @@ coverage==4.0
 cryptography==2.1
 ddt==1.0.1
 debtcollector==1.2.0
+doc8==0.6.0
 extras==1.0.0
 fasteners==0.7.0
 fixtures==3.0.0

test-requirements.txt

@@ -13,3 +13,4 @@ tempest>=17.1.0 # Apache-2.0
 testtools>=2.2.0 # MIT
 stestr>=1.0.0 # Apache-2.0
 oslo.serialization!=2.19.1,>=2.18.0 # Apache-2.0
+doc8>=0.6.0 # Apache-2.0

tox.ini

@@ -30,7 +30,9 @@ commands = find . -type f -name "*.pyc" -delete
 whitelist_externals = find
 
 [testenv:pep8]
-commands = flake8
+commands =
+  flake8
+  doc8
 
 [testenv:pylint]
 deps =
@@ -107,6 +109,10 @@ show-source = True
 ignore = H404,H405,E122,E123,E128,E251,W504
 exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build
 
+[doc8]
+ignore-path=.tox,*.egg-info,doc/src/api,doc/source/drivers.rst,doc/build,.eggs/*/EGG-INFO/*.txt,doc/so    urce/configuration/tables,./*.txt,releasenotes/build,doc/source/cli/details.rst
+extension=.txt,.rst,.inc
+
 [testenv:lower-constraints]
 deps =
   -c{toxinidir}/lower-constraints.txt