[test] add a line matcher object

doc/conf.py

@@ -1,11 +1,16 @@
 # Sphinx documentation build configuration file
+from __future__ import annotations
 
 import os
 import re
 import time
+from typing import TYPE_CHECKING
 
 import sphinx
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
 os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1'
 
 extensions = [
@@ -208,6 +213,13 @@
     ('py:class', 'sphinx.theming.Theme'),
     ('py:class', 'sphinxcontrib.websupport.errors.DocumentNotFoundError'),
     ('py:class', 'sphinxcontrib.websupport.errors.UserNotAuthorizedError'),
+    # stdlib
+    ('py:class', '_io.StringIO'),
+    ('py:class', 'typing_extensions.Self'),
+    ('py:class', 'typing_extensions.Unpack'),
+    # type variables
+    ('py:class', 'sphinx.testing.matcher.buffer.T'),
+    ('py:class', 'sphinx.testing.matcher.options.DT'),
     ('py:exc', 'docutils.nodes.SkipNode'),
     ('py:exc', 'sphinx.environment.NoUri'),
     ('py:func', 'setup'),
@@ -274,8 +286,9 @@ def linkify(match):
         source[0] = source[0].replace('.. include:: ../CHANGES.rst', linkified_changelog)
 
 
-def setup(app):
+def setup(app: Sphinx) -> None:
     from sphinx.ext.autodoc import cut_lines
+    from sphinx.roles import code_role
     from sphinx.util.docfields import GroupedField
 
     app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
@@ -290,3 +303,13 @@ def setup(app):
     app.add_object_type(
         'event', 'event', 'pair: %s; event', parse_event, doc_field_types=[fdesc]
     )
+
+    def pycode_role(name, rawtext, text, lineno, inliner, options=None, content=()):
+        options = (options or {}) | {'language': 'python'}
+        return code_role(name, rawtext, text, lineno, inliner, options, content)
+
+    def pyrepr_role(name, rawtext, text, lineno, inliner, options=None, content=()):
+        return pycode_role(name, rawtext, repr(text), lineno, inliner, options, content)
+
+    app.add_role('py3', pycode_role)
+    app.add_role('py3repr', pyrepr_role)

doc/development/index.rst

@@ -15,6 +15,7 @@ the extension interface see :doc:`/extdev/index`.
    overview
    tutorials/index
    builders
+   testing/index
 
 .. toctree::
    :caption: Theming

doc/development/testing/index.rst

@@ -0,0 +1,15 @@
+=======
+Testing
+=======
+
+The :mod:`!sphinx.testing` module provides utility classes, functions, fixtures
+and markers for testing with `pytest`_. Refer to the following sections to get
+started with testing integration.
+
+.. toctree::
+   :maxdepth: 1
+
+   plugin
+   matcher
+
+.. _pytest: https://docs.pytest.org/en/latest/

doc/development/testing/matcher.rst

@@ -0,0 +1,23 @@
+Testing the Sphinx output
+=========================
+
+.. automodule:: sphinx.testing.matcher
+   :members:
+   :member-order: bysource
+
+.. automodule:: sphinx.testing.matcher.options
+   :members:
+   :member-order: bysource
+
+.. automodule:: sphinx.testing.matcher.buffer
+   :members:
+   :member-order: bysource
+
+Utility functions
+-----------------
+
+.. automodule:: sphinx.testing.matcher.cleaner
+   :members:
+   :member-order: bysource
+   :ignore-module-all:
+

doc/development/testing/plugin.rst

@@ -0,0 +1,19 @@
+The Sphinx testing plugin
+=========================
+
+The testing plugin can be enabled by adding following line in  ``conftest.py``:
+
+.. code-block:: python
+   :caption: conftest.py
+
+   pytest_plugins = ['sphinx.testing.fixtures']
+
+This rest of the section is dedicated to documenting the testing features but
+the reader is assumed to have some prior knowledge on `pytest`_.
+
+.. warning::
+
+   This topic is incomplete and some features are not yet documented.
+
+.. _pytest: https://docs.pytest.org/en/latest/
+

pyproject.toml

@@ -80,6 +80,7 @@ dynamic = ["version"]
 [project.optional-dependencies]
 docs = [
     "sphinxcontrib-websupport",
+    "typing-extensions",
 ]
 lint = [
     "flake8>=3.5.0",
@@ -88,6 +89,7 @@ lint = [
     "sphinx-lint",
     "types-docutils",
     "types-requests",
+    "typing-extensions",
     "importlib_metadata",  # for mypy (Python<=3.9)
     "tomli",  # for mypy (Python<=3.10)
     "pytest>=6.0",