Replace doclinter with sphinx-lint (#10389)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
sphinx-doc · Jun 16, 2022 · 956cddb · 956cddb
1 parent 2a88d80
commit 956cddb
Show file tree

Hide file tree

Showing 14 changed files with 24 additions and 101 deletions.
diff --git a/.github/workflows/lint.yml b/.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

diff --git a/Makefile b/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:

diff --git a/doc/development/index.rst b/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`.
 

diff --git a/doc/development/tutorials/autodoc_ext.rst b/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
-
-
diff --git a/doc/extdev/deprecated.rst b/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()``
 

diff --git a/doc/latex.rst b/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

diff --git a/doc/templating.rst b/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.
 

diff --git a/doc/tutorial/describing-code.rst b/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

diff --git a/doc/usage/extensions/intersphinx.rst b/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

diff --git a/doc/usage/extensions/napoleon.rst b/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.
 

diff --git a/doc/usage/installation.rst b/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.

diff --git a/setup.py b/setup.py
@@ -42,6 +42,7 @@
         'flake8>=3.5.0',
         'isort',
         'mypy>=0.950',
+        'sphinx-lint',
         'docutils-stubs',
         "types-typed-ast",
         "types-requests",

diff --git a/tox.ini b/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

diff --git a/utils/doclinter.py b/utils/doclinter.py