[lint] update Makefile and lint doc (#12117)

Makefile

@@ -19,7 +19,7 @@ clean: clean
 	# clean generated:
 	find . -name '.DS_Store' -exec rm -f {} +
 
-	# clean rendered documentation :
+	# clean rendered documentation:
 	rm -rf doc/build/
 	rm -rf doc/_build/
 	rm -rf build/sphinx/
@@ -34,6 +34,7 @@ clean: clean
 	rm -rf .tox/
 	rm -rf .cache/
 	find . -name '.pytest_cache' -exec rm -rf {} +
+	rm -f tests/test-server.lock
 
 	# clean build files:
 	rm -rf dist/
@@ -41,15 +42,18 @@ clean: clean
 
 .PHONY: style-check
 style-check:
-	@ruff
+	@ruff check .
 
 .PHONY: type-check
 type-check:
-	mypy sphinx
+	@mypy
 
 .PHONY: doclinter
 doclinter:
-	sphinx-lint --enable line-too-long --max-line-length 85 *.rst doc/
+	@sphinx-lint --enable all --max-line-length 85 --disable triple-backticks \
+	             -i CHANGES.rst -i LICENSE.rst -i EXAMPLES.rst \
+	             $(addprefix -i doc/, _build _static _templates _themes) \
+	             *.rst doc/ 2>&1 | sort -V
 
 .PHONY: test
 test:

doc/development/templating.rst

@@ -108,7 +108,7 @@ The following blocks exist in the ``layout.html`` template:
     parent documents on the left, and the links to index, modules etc. on the
     right).  ``relbar1`` appears before the document, ``relbar2`` after the
     document.  By default, both blocks are filled; to show the relbar only
-    before the document, you would override `relbar2` like this::
+    before the document, you would override ``relbar2`` like this::
 
        {% block relbar2 %}{% endblock %}
 
@@ -422,7 +422,7 @@ are in HTML form), these variables are also available:
 .. data:: next
 
    The next document for the navigation.  This variable is either false or has
-   two attributes `link` and `title`.  The title contains HTML markup.  For
+   two attributes ``link`` and ``title``.  The title contains HTML markup.  For
    example, to generate a link to the next page, you can use this snippet::
 
       {% if next %}

doc/extdev/i18n.rst

@@ -18,8 +18,8 @@ i18n API
 
 .. _ext-i18n:
 
-Extension internationalization (`i18n`) and localization (`l10n`) using i18n API
---------------------------------------------------------------------------------
+Extension internationalization (``i18n``) and localization (``l10n``) using i18n API
+------------------------------------------------------------------------------------
 
 .. versionadded:: 1.8
 

doc/extdev/nodes.rst

@@ -44,7 +44,7 @@ to ``docutils.nodes.inline`` by :py:class:`!SigElementFallbackTransform`.
 Extensions may create additional ``desc_sig_*``-like nodes but in order for
 :py:class:`!SigElementFallbackTransform` to translate them to inline nodes
 automatically, they must be added to :py:data:`SIG_ELEMENTS` via the class
-keyword argument `_sig_element=True` of :py:class:`desc_sig_element`, e.g.:
+keyword argument ``_sig_element=True`` of :py:class:`desc_sig_element`, e.g.:
 
    .. code-block:: python
 

doc/latex.rst

@@ -377,7 +377,7 @@ Keys that don't need to be overridden unless in special cases are:
    .. versionchanged:: 2.0
       ``'lualatex'`` executes
       ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX
-      ligatures transforming `<<` and `>>` as escaping working with
+      ligatures transforming ``<<`` and ``>>`` as escaping working with
       ``pdflatex/xelatex`` failed with ``lualatex``.
 
    .. versionchanged:: 2.0

doc/usage/advanced/websupport/quickstart.rst

@@ -137,7 +137,7 @@ add this data to the ``COMMENT_OPTIONS`` that are used in the template.
 
    This only works if your documentation is served from your
    document root. If it is served from another directory, you will
-   need to prefix the url route with that directory, and give the `docroot`
+   need to prefix the url route with that directory, and give the *docroot*
    keyword argument when creating the web support object::
 
       support = WebSupport(..., docroot='docs')
@@ -150,7 +150,7 @@ Performing Searches
 
 To use the search form built-in to the Sphinx sidebar, create a function to
 handle requests to the URL 'search' relative to the documentation root.  The
-user's search query will be in the GET parameters, with the key `q`.  Then use
+user's search query will be in the GET parameters, with the key ``q``.  Then use
 the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
 retrieve search results. In `Flask <https://flask.palletsprojects.com/>`_ that
 would be like this::

doc/usage/advanced/websupport/searchadapters.rst

@@ -7,7 +7,7 @@ Search Adapters
 
 To create a custom search adapter you will need to subclass the
 :class:`BaseSearch` class.  Then create an instance of the new class and pass
-that as the `search` keyword argument when you create the :class:`~.WebSupport`
+that as the *search* keyword argument when you create the :class:`~.WebSupport`
 object::
 
    support = WebSupport(srcdir=srcdir,

doc/usage/advanced/websupport/storagebackends.rst

@@ -7,7 +7,7 @@ Storage Backends
 
 To create a custom storage backend you will need to subclass the
 :class:`StorageBackend` class.  Then create an instance of the new class and
-pass that as the `storage` keyword argument when you create the
+pass that as the *storage* keyword argument when you create the
 :class:`~.WebSupport` object::
 
    support = WebSupport(srcdir=srcdir,

doc/usage/builders/index.rst

@@ -353,8 +353,8 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
 .. class:: SerializingHTMLBuilder
 
    This builder uses a module that implements the Python serialization API
-   (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated
-   HTML documentation.  The pickle builder is a subclass of it.
+   (``pickle``, ``simplejson``, ``phpserialize``, and others) to dump the
+   generated HTML documentation.  The pickle builder is a subclass of it.
 
    A concrete subclass of this builder serializing to the `PHP serialization`_
    format could look like this::
@@ -372,10 +372,10 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
 
    .. attribute:: implementation
 
-      A module that implements `dump()`, `load()`, `dumps()` and `loads()`
+      A module that implements ``dump()``, ``load()``, ``dumps()`` and ``loads()``
       functions that conform to the functions with the same names from the
       pickle module.  Known modules implementing this interface are
-      `simplejson`, `phpserialize`, `plistlib`, and others.
+      ``simplejson``, ``phpserialize``, ``plistlib``, and others.
 
    .. attribute:: out_suffix
 

doc/usage/configuration.rst

@@ -1676,7 +1676,7 @@ Options for Single HTML output
 .. confval:: singlehtml_sidebars
 
    Custom sidebar templates, must be a dictionary that maps document names to
-   template names.  And it only allows a key named `'index'`.  All other keys
+   template names.  And it only allows a key named ``'index'``.  All other keys
    are ignored.  For more information, refer to :confval:`html_sidebars`.  By
    default, it is same as :confval:`html_sidebars`.
 
@@ -3113,7 +3113,7 @@ Options for the Python domain
    for the latter, the signature length ignores the length of
    the type parameters list.
 
-   For instance, with `python_maximum_signature_line_length = 20`,
+   For instance, with ``python_maximum_signature_line_length = 20``,
    only the list of type parameters will be wrapped
    while the arguments list will be rendered on a single line
 

doc/usage/domains/cpp.rst

@@ -563,7 +563,7 @@ following fields:
 * ``returns``, ``return``: Description of a return value.
 * ``retval``, ``retvals``: An alternative to ``returns`` for describing
   the result of the function.
-* `throws`, `throw`, `exception`: Description of a possibly thrown exception.
+* ``throws``, ``throw``, ``exception``: Description of a possibly thrown exception.
 
 .. versionadded:: 4.3
    The ``retval`` field type.

doc/usage/extensions/napoleon.rst

@@ -63,14 +63,14 @@ Getting Started
 ~~~~~~~~~~~~~~~
 
 1. After :doc:`setting up Sphinx </usage/quickstart>` to build your docs,
-   enable napoleon in the Sphinx `conf.py` file::
+   enable napoleon in the Sphinx ``conf.py`` file::
 
        # conf.py
 
        # Add napoleon to the extensions list
        extensions = ['sphinx.ext.napoleon']
 
-2. Use `sphinx-apidoc` to build your API documentation::
+2. Use ``sphinx-apidoc`` to build your API documentation::
 
        $ sphinx-apidoc -f -o docs/source projectdir
 
@@ -271,8 +271,8 @@ Configuration
 -------------
 
 Listed below are all the settings used by napoleon and their default
-values. These settings can be changed in the Sphinx `conf.py` file. Make
-sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
+values. These settings can be changed in the Sphinx ``conf.py`` file. Make
+sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
 
     # conf.py
 

doc/usage/referencing.rst

@@ -197,8 +197,8 @@ Cross-referencing figures by figure number
 .. versionadded:: 1.3
 
 .. versionchanged:: 1.5
-   `numref` role can also refer sections.
-   And `numref` allows `{name}` for the link text.
+   :rst:role:`numref` role can also refer sections.
+   And :rst:role:`numref` allows ``{name}`` for the link text.
 
 .. rst:role:: numref
 

doc/usage/restructuredtext/field-lists.rst

@@ -73,6 +73,6 @@ At the moment, these metadata fields are recognized:
 
        :nosearch:
 
-   .. note:: object search is still available even if `nosearch` option is set.
+   .. note:: object search is still available even if ``nosearch`` option is set.
 
    .. versionadded:: 3.0

doc/usage/theming.rst

@@ -325,10 +325,10 @@ These themes are:
   are supported:
 
   - **relbar1** (true or false, default ``True``): If this is true, the
-    `relbar1` block is inserted in the epub output, otherwise it is omitted.
+    ``relbar1`` block is inserted in the epub output, otherwise it is omitted.
 
   - **footer**  (true or false, default ``True``): If this is true, the
-    `footer` block is inserted in the epub output, otherwise it is omitted.
+    ``footer`` block is inserted in the epub output, otherwise it is omitted.
 
 **bizstyle**
   A simple bluish theme. The following options are supported