Replace doclinter with sphinx-lint (#10389)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

.github/workflows/lint.yml

@@ -13,9 +13,9 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
-        python-version: 3.6
+        python-version: '>=3.7'
     - name: Install dependencies
       run:  pip install -U tox
     - name: Run Tox

Makefile

@@ -62,7 +62,7 @@ type-check:
 
 .PHONY: doclinter
 doclinter:
-	python utils/doclinter.py CHANGES *.rst doc/
+	sphinx-lint --enable line-too-long --max-line-length 85 CHANGES *.rst doc/
 
 .PHONY: test
 test:

doc/development/index.rst

@@ -2,10 +2,10 @@
 Extending Sphinx
 ================
 
-This guide is aimed at giving a quick introduction for those wishing to 
-develop their own extensions for Sphinx. Sphinx possesses significant 
+This guide is aimed at giving a quick introduction for those wishing to
+develop their own extensions for Sphinx. Sphinx possesses significant
 extensibility capabilities including the ability to hook into almost every
-point of the build process.  If you simply wish to use Sphinx with existing 
+point of the build process.  If you simply wish to use Sphinx with existing
 extensions, refer to :doc:`/usage/index`. For a more detailed discussion of
 the extension interface see :doc:`/extdev/index`.
 

doc/development/tutorials/autodoc_ext.rst

@@ -123,7 +123,7 @@ For example, you have the following ``IntEnum``:
 
 .. code-block:: python
    :caption: my_enums.py
-   
+
    class Colors(IntEnum):
        """Colors enumerator"""
        NONE = 0
@@ -138,5 +138,3 @@ This will be the documentation file with auto-documentation directive:
    :caption: index.rst
 
    .. autointenum:: my_enums.Colors
-
-

doc/extdev/deprecated.rst

@@ -824,7 +824,7 @@ The following is a list of deprecated interfaces.
      - ``sphinx.domains.std.StandardDomain.process_doc()``
 
    * - ``sphinx.domains.js.JSObject.display_prefix``
-     - 
+     -
      - 4.3
      - ``sphinx.domains.js.JSObject.get_display_prefix()``
 

doc/latex.rst

@@ -330,7 +330,7 @@ Keys that don't need to be overridden unless in special cases are:
 
    .. attention::
 
-      - Do not use this key for a :confval:`latex_engine` other than 
+      - Do not use this key for a :confval:`latex_engine` other than
         ``'pdflatex'``.
 
       - If Greek is main language, do not use this key.  Since Sphinx 2.2.1,
@@ -528,7 +528,7 @@ Keys that don't need to be overridden unless in special cases are:
       is adapted to the relative widths of the FreeFont family.
 
    .. versionchanged:: 4.0.0
-      Changed default for ``'pdflatex'``. Previously it was using 
+      Changed default for ``'pdflatex'``. Previously it was using
       ``'\\fvset{fontsize=\\small}'``.
 
    .. versionchanged:: 4.1.0
@@ -915,7 +915,7 @@ Do not use quotes to enclose values, whether numerical or strings.
                                ``attentionBorderColor``, ``dangerBorderColor``,
                                ``errorBorderColor``
 
-.. |wgbdcolorslatex| replace:: ``warningBorderColor``, and 
+.. |wgbdcolorslatex| replace:: ``warningBorderColor``, and
                                ``(caution|attention|danger|error)BorderColor``
 
 .. else latex goes into right margin, as it does not hyphenate the names

doc/templating.rst

@@ -377,7 +377,7 @@ in the future.
 .. data:: sphinx_version_tuple
 
    The version of Sphinx used to build represented as a tuple of five elements.
-   For Sphinx version 3.5.1 beta 3 this would be `(3, 5, 1, 'beta', 3)``.
+   For Sphinx version 3.5.1 beta 3 this would be ``(3, 5, 1, 'beta', 3)``.
    The fourth element can be one of: ``alpha``, ``beta``, ``rc``, ``final``.
    ``final`` always has 0 as the last element.
 

doc/tutorial/describing-code.rst

@@ -85,10 +85,11 @@ you can use :rst:role:`py:func` for that, as follows:
    or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
    will raise an exception.
 
-When generating code documentation, Sphinx will generate a cross-reference automatically just
-by using the name of the object, without you having to explicitly use a role
-for that. For example, you can describe the custom exception raised by the
-function using the :rst:dir:`py:exception` directive:
+When generating code documentation, Sphinx will generate a
+cross-reference automatically just by using the name of the object,
+without you having to explicitly use a role for that. For example, you
+can describe the custom exception raised by the function using the
+:rst:dir:`py:exception` directive:
 
 .. code-block:: rst
    :caption: docs/source/usage.rst

doc/usage/extensions/intersphinx.rst

@@ -209,7 +209,7 @@ The Intersphinx extension provides the following role.
 
    If you would like to constrain the lookup to a specific external project,
    then the key of the project, as specified in :confval:`intersphinx_mapping`,
-   is added as well to get the two forms 
+   is added as well to get the two forms
 
    - ``:external+invname:domain:reftype:`target```,
      e.g., ``:external+python:py:class:`zipfile.ZipFile```, or

doc/usage/extensions/napoleon.rst

@@ -221,7 +221,7 @@ Google style with Python 3 type annotations::
 
         """
         return True
-    
+
     class Class:
         """Summary line.
 
@@ -251,7 +251,7 @@ Google style with types in docstrings::
 
         """
         return True
-    
+
     class Class:
         """Summary line.
 

doc/usage/installation.rst

@@ -118,7 +118,7 @@ Chocolatey
 ::
 
    $ choco install sphinx
-   
+
 You would need to `install Chocolatey
 <https://chocolatey.org/install>`_
 before running this.

setup.py

@@ -42,6 +42,7 @@ extras_require = {
         'flake8>=3.5.0',
         'isort',
         'mypy>=0.950',
+        'sphinx-lint',
         'docutils-stubs',
         "types-typed-ast",
         "types-requests",

tox.ini

@@ -81,9 +81,9 @@ basepython = python3
 description =
     Lint documentation.
 extras =
-    docs
+    lint
 commands =
-    python utils/doclinter.py CHANGES CONTRIBUTING.rst README.rst doc/
+    sphinx-lint --disable missing-space-after-literal --enable line-too-long --max-line-length 85 CHANGES CONTRIBUTING.rst README.rst doc/
 
 [testenv:twine]
 basepython = python3

utils/doclinter.py

@@ -1,77 +0,0 @@
-"""A linter for Sphinx docs"""
-
-import os
-import re
-import sys
-from typing import List
-
-MAX_LINE_LENGTH = 85
-LONG_INTERPRETED_TEXT = re.compile(r'^\s*\W*(:(\w+:)+)?`.*`\W*$')
-CODE_BLOCK_DIRECTIVE = re.compile(r'^(\s*)\.\. code-block::')
-LEADING_SPACES = re.compile(r'^(\s*)')
-
-
-def lint(path: str) -> int:
-    with open(path, encoding='utf-8') as f:
-        document = f.readlines()
-
-    errors = 0
-    in_code_block = False
-    code_block_depth = 0
-    for i, line in enumerate(document):
-        if line.endswith(' '):
-            print('%s:%d: the line ends with whitespace.' %
-                  (path, i + 1))
-            errors += 1
-
-        matched = CODE_BLOCK_DIRECTIVE.match(line)
-        if matched:
-            in_code_block = True
-            code_block_depth = len(matched.group(1))
-        elif in_code_block:
-            if line.strip() == '':
-                pass
-            else:
-                spaces = LEADING_SPACES.match(line).group(1)
-                if len(spaces) <= code_block_depth:
-                    in_code_block = False
-        elif LONG_INTERPRETED_TEXT.match(line):
-            pass
-        elif len(line) > MAX_LINE_LENGTH:
-            if re.match(r'^\s*\.\. ', line):
-                # ignore directives and hyperlink targets
-                pass
-            elif re.match(r'^\s*__ ', line):
-                # ignore anonymous hyperlink targets
-                pass
-            elif re.match(r'^\s*``[^`]+``$', line):
-                # ignore a very long literal string
-                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 path in args:
-        if os.path.isfile(path):
-            errors += lint(path)
-        elif os.path.isdir(path):
-            for root, _dirs, files in os.walk(path):
-                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:]))