Added doc8

For a better doc QoS, we now use doc8 as part of the testing
procedure while removing the existing tests we had on doc formatting.

I also updated tox.ini to run doc8 as within 'pep8' and 'docs' venvs.

Change-Id: Ia0ad99541509f4c026e26d28c41ff0210b12a504
Closes-Bug: #1524228

doc/source/dev/environment.rst

@@ -75,17 +75,13 @@ extension, PyPi) cannot satisfy. These dependencies should be installed
 prior to using `pip`, and the installation method may vary depending on
 your platform.
 
-* Ubuntu 14.04:
+* Ubuntu 14.04::
 
-  .. code-block:: bash
+    $ sudo apt-get install python-dev libssl-dev libmysqlclient-dev libffi-dev
 
-      $ sudo apt-get install python-dev libssl-dev libmysqlclient-dev libffi-dev
+* Fedora 19+::
 
-* Fedora 19+:
-
-  .. code-block:: bash
-
-      $ sudo yum install openssl-devel libffi-devel mysql-devel
+    $ sudo yum install openssl-devel libffi-devel mysql-devel
 
 
 PyPi Packages and VirtualEnv
@@ -287,4 +283,3 @@ template files to easily play with Watcher services within a minimal OpenStack
 isolated environment (Identity, Message Bus, SQL database, Horizon, ...).
 
 .. _`watcher-tools`: https://github.com/b-com/watcher-tools
-

doc/source/man/footer.rst

@@ -1,4 +1,5 @@
 BUGS
 ====
 
-* Watcher bugs are tracked in Launchpad at `OpenStack Watcher <http://bugs.launchpad.net/watcher>`__
+* Watcher bugs are tracked in Launchpad at `OpenStack Watcher
+  <http://bugs.launchpad.net/watcher>`__

doc/source/man/general-options.rst

@@ -63,4 +63,4 @@
 
   **--log-dir LOG_DIR, --logdir LOG_DIR**
         (Optional) The directory to keep log files in (will be prepended
-        to --log-file)
+        to --log-file)

test-requirements.txt

@@ -4,6 +4,7 @@
 
 coverage>=3.6
 discover
+doc8 # Apache-2.0
 hacking>=0.10.2,<0.11
 mock>=1.2
 oslotest>=1.10.0  # Apache-2.0
@@ -19,4 +20,5 @@ sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
 sphinxcontrib-pecanwsme>=0.8
 
 # For PyPI distribution
-twine
+twine
+

tox.ini

@@ -17,7 +17,9 @@ commands =
   ostestr --concurrency=6 {posargs}
 
 [testenv:pep8]
-commands = flake8
+commands =
+    doc8 doc/source/ CONTRIBUTING.rst HACKING.rst README.rst
+    flake8
 
 [testenv:venv]
 setenv = PYTHONHASHSEED=0
@@ -28,7 +30,9 @@ commands = python setup.py testr --coverage --omit="watcher/tests/*" --testr-arg
 
 [testenv:docs]
 setenv = PYTHONHASHSEED=0
-commands = python setup.py build_sphinx
+commands =
+    doc8 doc/source/ CONTRIBUTING.rst HACKING.rst README.rst
+    python setup.py build_sphinx
 
 [testenv:debug]
 commands = oslo_debug_helper {posargs}
@@ -59,3 +63,8 @@ commands = python setup.py bdist_wheel
 
 [hacking]
 import_exceptions = watcher._i18n
+
+[doc8]
+extension=.rst
+# todo: stop ignoring doc/source/man when https://bugs.launchpad.net/doc8/+bug/1502391 is fixed
+ignore-path=doc/source/image_src,doc/source/man

watcher/tests/test_doc_formatting.py

@@ -1,79 +0,0 @@
-# Licensed under the Apache License, Version 2.0 (the "License"); you may
-# not use this file except in compliance with the License. You may obtain
-# a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-# License for the specific language governing permissions and limitations
-# under the License.
-import os
-import re
-import testtools
-
-
-class TestDocFormatting(testtools.TestCase):
-    def _check_lines_wrapping(self, tpl, raw):
-        code_block = False
-        for i, line in enumerate(raw.split("\n"), start=1):
-            # NOTE(ndipanov): Allow code block lines to be longer than 79 ch
-            if code_block:
-                if not line or line.startswith(" "):
-                    continue
-                else:
-                    code_block = False
-            if "::" in line:
-                code_block = True
-            if "http://" in line or "https://" in line:
-                continue
-            # Allow lines which do not contain any whitespace
-            if re.match("\s*[^\s]+$", line):
-                continue
-            if code_block is False:
-                self.assertTrue(
-                    len(line) < 80,
-                    msg="%s:%d: Line limited to a maximum of 79 characters." %
-                        (tpl, i))
-
-    def _check_no_cr(self, tpl, raw):
-        cr = '\r'
-        matches = re.findall(cr, raw)
-        self.assertEqual(
-            len(matches), 0,
-            "Found %s literal carriage returns in file %s" %
-            (len(matches), tpl))
-
-    def _check_trailing_spaces(self, tpl, raw):
-        for i, line in enumerate(raw.split("\n"), start=1):
-            trailing_spaces = re.findall(" +$", line)
-            self.assertEqual(len(trailing_spaces), 0,
-                             "Found trailing spaces on line %s of %s" % (
-                                 i, tpl))
-
-    def _check_tab(self, tpl, raw):
-        tab = '\t'
-        matches = re.findall(tab, raw)
-        self.assertEqual(
-            len(matches), 0,
-            "Found %s tab in file %s" %
-            (len(matches), tpl))
-
-    def test_template(self):
-        doc_path = os.path.join("doc", 'source')
-        for root, dirs, files in os.walk(top=doc_path):
-            for file in files:
-                absolute_path_file = os.path.join(root, file)
-
-                if not os.path.isdir(absolute_path_file):
-                    if not absolute_path_file.endswith(".rst"):
-                        continue
-
-                    with open(absolute_path_file) as f:
-                        data = f.read()
-
-                    self._check_tab(absolute_path_file, data)
-                    self._check_lines_wrapping(absolute_path_file, data)
-                    self._check_no_cr(absolute_path_file, data)
-                    self._check_trailing_spaces(absolute_path_file, data)