Merge pull request #6356 from tk0miya/foldlines

Add utils/doclinter.py; a documenter linter for Sphinx

doc/develop.rst

@@ -31,7 +31,8 @@ This is the current list of contributed extensions in that repository:
 - actdiag: embed activity diagrams by using actdiag_
 - adadomain: an extension for Ada support (Sphinx 1.0 needed)
 - ansi: parse ANSI color sequences inside documents
-- argdoc: automatically generate documentation for command-line arguments, descriptions, and help text
+- argdoc: automatically generate documentation for command-line arguments,
+  descriptions and help text
 - astah: embed diagram by using astah
 - autoanysrc: Gather reST documentation from any source files
 - autorun: Execute code in a ``runblock`` directive
@@ -64,7 +65,8 @@ This is the current list of contributed extensions in that repository:
 - imgur: embed Imgur images, albums, and metadata in documents
 - inlinesyntaxhighlight_: inline syntax highlighting
 - lassodomain: a domain for documenting Lasso_ source code
-- libreoffice: an extension to include any drawing supported by LibreOffice (e.g. odg, vsd, ...)
+- libreoffice: an extension to include any drawing supported by LibreOffice
+  (e.g. odg, vsd, ...)
 - lilypond: an extension inserting music scripts from Lilypond_ in PNG format
 - makedomain_: a domain for `GNU Make`_
 - matlabdomain: document MATLAB_ code
@@ -100,8 +102,8 @@ This is the current list of contributed extensions in that repository:
 - zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_
 
 
-See the :doc:`extension tutorials <../development/tutorials/index>` on getting started with writing your
-own extensions.
+See the :doc:`extension tutorials <../development/tutorials/index>` on getting
+started with writing your own extensions.
 
 
 .. _aafigure: https://launchpad.net/aafigure

doc/extdev/index.rst

@@ -97,7 +97,8 @@ extension. These are:
 
    The config is available as ``app.config`` or ``env.config``.
 
-To see an example of use of these objects, refer to :doc:`../development/tutorials/index`.
+To see an example of use of these objects, refer to
+:doc:`../development/tutorials/index`.
 
 .. _build-phases:
 

doc/extdev/markupapi.rst

@@ -147,5 +147,6 @@ return ``node.children`` from the Directive.
 
 .. seealso::
 
-   `Creating directives <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_
-      HOWTO of the Docutils documentation
+   `Creating directives`_ HOWTO of the Docutils documentation
+
+.. _Creating directives: http://docutils.sourceforge.net/docs/howto/rst-directives.html

doc/templating.rst

@@ -354,8 +354,8 @@ are in HTML form), these variables are also available:
 
 .. data:: body
 
-   A string containing the content of the page in HTML form as produced by the HTML builder,
-   before the theme is applied.
+   A string containing the content of the page in HTML form as produced by the
+   HTML builder, before the theme is applied.
 
 .. data:: display_toc
 
@@ -382,8 +382,9 @@ are in HTML form), these variables are also available:
 
 .. data:: page_source_suffix
 
-   The suffix of the file that was rendered. Since we support a list of :confval:`source_suffix`,
-   this will allow you to properly link to the original source file.
+   The suffix of the file that was rendered. Since we support a list of
+   :confval:`source_suffix`, this will allow you to properly link to the
+   original source file.
 
 .. data:: parents
 

doc/usage/restructuredtext/domains.rst

@@ -1083,15 +1083,16 @@ These roles link to the given declaration types:
 
 .. admonition:: Note on References with Templates Parameters/Arguments
 
-   These roles follow the Sphinx :ref:`xref-syntax` rules. This means care must be
-   taken when referencing a (partial) template specialization, e.g. if the link looks like
-   this: ``:cpp:class:`MyClass<int>```.
+   These roles follow the Sphinx :ref:`xref-syntax` rules. This means care must
+   be taken when referencing a (partial) template specialization, e.g. if the
+   link looks like this: ``:cpp:class:`MyClass<int>```.
    This is interpreted as a link to ``int`` with a title of ``MyClass``.
    In this case, escape the opening angle bracket with a backslash,
    like this: ``:cpp:class:`MyClass\<int>```.
 
-   When a custom title is not needed it may be useful to use the roles for inline expressions,
-   :rst:role:`cpp:expr` and :rst:role:`cpp:texpr`, where angle brackets do not need escaping.
+   When a custom title is not needed it may be useful to use the roles for
+   inline expressions, :rst:role:`cpp:expr` and :rst:role:`cpp:texpr`, where
+   angle brackets do not need escaping.
 
 Declarations without template parameters and template arguments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

tox.ini

@@ -66,6 +66,15 @@ extras =
 commands =
     python setup.py build_sphinx {posargs}
 
+[testenv:docslint]
+basepython = python3
+description =
+    Lint documentation.
+extras =
+    docs
+commands =
+    python utils/doclinter.py CHANGES CONTRIBUTING.rst README.rst doc/
+
 [testenv:bindep]
 description =
     Install binary dependencies.

utils/doclinter.py

@@ -0,0 +1,59 @@
+"""
+    utils.doclinter
+    ~~~~~~~~~~~~~~~
+
+    A linter for Sphinx docs
+
+    :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import os
+import re
+import sys
+from typing import List
+
+
+MAX_LINE_LENGTH = 100
+
+
+def lint(path: str) -> int:
+    with open(path) as f:
+        document = f.readlines()
+
+    errors = 0
+    for i, line in enumerate(document):
+        if line.endswith(' '):
+            print('%s:%d: the line ends with whitespace.' %
+                  (path, i + 1))
+            errors += 1
+
+        if len(line) > MAX_LINE_LENGTH:
+            if re.match(r'^\s*\.\. ', line):
+                # ignore directives and hyperlink targets
+                pass
+            else:
+                print('%s:%d: the line is too long (%d > %d).' %
+                      (path, i + 1, len(line), MAX_LINE_LENGTH))
+                errors += 1
+
+    return errors
+
+
+def main(args: List[str]) -> int:
+    errors = 0
+    for directory in args:
+        for root, dirs, files in os.walk(directory):
+            for filename in files:
+                if filename.endswith('.rst'):
+                    path = os.path.join(root, filename)
+                    errors += lint(path)
+
+    if errors:
+        return 1
+    else:
+        return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))