Run doc8 as part of pep8 test

Fix all issues found and enable doc8 run.

Change-Id: I1b3fc9ac3db5e2d1dfa138b026e26835ead4d7fb

RELEASE_NOTES.rst

@@ -19,7 +19,7 @@ Release notes
 0.17
 ----
 
-* Added support for *-manage CLI doc generation.
+* Added support for ``*-manage`` CLI doc generation.
 * ``openstack-dn2osdbk``: Converts Docutils Native XML to docbook.
 * ``openstack-doc-test``: Handle the upcoming HOT guide.
 * ``autohelp.py``: Provide our own sanitizer.
@@ -99,7 +99,7 @@ Release notes
 ----
 
 * Fix ``openstack-doc-test`` to handle changes in ``api-site`` repository:
-  Do not publish wadls directory, *.fo files and add api-ref-guides
+  Do not publish wadls directory, ``*.fo`` files and add api-ref-guides
   PDF files to index file for docs-draft.
 * Many improvements for generation of option tables.
 * Improvements for ``openstack-auto-commands``: handle ironic, sahara;
@@ -110,7 +110,8 @@ Release notes
 
 Fixes for openstack-doc-test:
 
-* openstack-doc-test now validates JSON files for well-formed-ness and whitespace.
+* openstack-doc-test now validates JSON files for well-formed-ness and
+  whitespace.
 * Create proper chapter title for markdown files.
 * Ignore publish-docs directory completely.
 * Do not check for xml:ids in wadl resource.

doc/source/man/openstack-doc-test.rst

@@ -14,7 +14,8 @@ openstack-doc-test [options]
 DESCRIPTION
 ===========
 
-openstack-doc-test allows to test the validity of the OpenStack documentation content.
+openstack-doc-test allows to test the validity of the OpenStack
+documentation content.
 
 OPTIONS
 =======

doc/source/release_notes.rst

@@ -1 +1,2 @@
+
 .. include:: ../../RELEASE_NOTES.rst

doc/source/usage.rst

@@ -4,4 +4,4 @@ Usage
 
 To use openstack-doc-tools in a project::
 
-	import os_doc_tools
+        import os_doc_tools

test-requirements.txt

@@ -1,3 +1,4 @@
+doc8
 # Hacking already pins down pep8, pyflakes and flake8
 hacking>=0.9.2,<0.10
 pylint==0.25.2

tox.ini

@@ -12,7 +12,12 @@ deps = -r{toxinidir}/requirements.txt
        -r{toxinidir}/test-requirements.txt
 
 [testenv:pep8]
-commands = flake8
+commands =
+    flake8
+    # Run doc8 to check .rst and .txt files.
+    # HACKING.rst is the only file that is not referenced from
+    # doc/source, so add it explicitely.
+    doc8 -e txt -e rst doc/source/ HACKING.rst
 
 [testenv:pylint]
 commands = pylint os_doc_tools cleanup