[lint] update and fix linter issues

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,22 +34,26 @@ 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/
  rm -rf build/
 
 .PHONY: style-check
 style-check:
- @ruff
+ @ruff check sphinx tests utils
 
 .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