From 4305935312004c1577c64c84f0a88b006a2a0b63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vincent=20Fran=C3=A7oise?= Date: Fri, 22 Jan 2016 14:55:21 +0100 Subject: [PATCH] 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 | 13 ++--- doc/source/man/footer.rst | 3 +- doc/source/man/general-options.rst | 2 +- test-requirements.txt | 4 +- tox.ini | 13 ++++- watcher/tests/test_doc_formatting.py | 79 ---------------------------- 6 files changed, 21 insertions(+), 93 deletions(-) delete mode 100644 watcher/tests/test_doc_formatting.py diff --git a/doc/source/dev/environment.rst b/doc/source/dev/environment.rst index 0a64c28a6..a3e009228 100644 --- a/doc/source/dev/environment.rst +++ b/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 - diff --git a/doc/source/man/footer.rst b/doc/source/man/footer.rst index 584b173a9..fc8c28e60 100644 --- a/doc/source/man/footer.rst +++ b/doc/source/man/footer.rst @@ -1,4 +1,5 @@ BUGS ==== -* Watcher bugs are tracked in Launchpad at `OpenStack Watcher `__ \ No newline at end of file +* Watcher bugs are tracked in Launchpad at `OpenStack Watcher + `__ diff --git a/doc/source/man/general-options.rst b/doc/source/man/general-options.rst index 7f9185679..71aa842e4 100644 --- a/doc/source/man/general-options.rst +++ b/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) \ No newline at end of file + to --log-file) diff --git a/test-requirements.txt b/test-requirements.txt index 91d2b593f..1156d1ac2 100644 --- a/test-requirements.txt +++ b/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 \ No newline at end of file +twine + diff --git a/tox.ini b/tox.ini index e9a365ff0..b0802fa51 100644 --- a/tox.ini +++ b/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 diff --git a/watcher/tests/test_doc_formatting.py b/watcher/tests/test_doc_formatting.py deleted file mode 100644 index 224f3d76a..000000000 --- a/watcher/tests/test_doc_formatting.py +++ /dev/null @@ -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)