pyTooling.Sphinx

Summary

Doc-string:

documented

File	Expected	Covered	Uncovered	Coverage
__init__.py	74	74	0	100.0%
Overall (25 files)	920	917	3	99.7%

Packages

Package	Expected	Covered	Uncovered	Coverage
Resources	1	1	0	100.0%

Modules

Module	Expected	Covered	Uncovered	Coverage
Abbreviation	41	41	0	100.0%
CodeCoverage	70	70	0	100.0%
CodeCoveragePages	22	22	0	100.0%
CondensedClass	28	27	1	96.4%
CondensedSource	28	28	0	100.0%
DependencyTable	103	101	2	98.1%
DocCoverage	76	76	0	100.0%
ExternalLink	61	61	0	100.0%
GitHubMarkdown	30	30	0	100.0%
HTML	50	50	0	100.0%
LaTeX	24	24	0	100.0%
Markdown	44	44	0	100.0%
Node	25	25	0	100.0%
Pages	34	34	0	100.0%
Roles	7	7	0	100.0%
SchemaGraph	13	13	0	100.0%
Shields	32	32	0	100.0%
Tree	31	31	0	100.0%
UnicodeTable	48	48	0	100.0%
Unittest	51	51	0	100.0%
UnittestPages	14	14	0	100.0%
Workaround	6	6	0	100.0%
XMLSchemaGraph	7	7	0	100.0%

Source

pyTooling.Sphinx/__init__.pydocumentedundocumentedignoredexcludednot counted

"""
A Sphinx extension providing the roles, nodes and directives shared by pyTooling and its sibling projects.

Every project in the family used to carry its own :file:`doc/prolog.inc` - eighteen hand-copied files, 36 to 67
lines each, already drifted apart - declaring the same roles as **ReST source** that is re-parsed into every
document of every project. This extension declares them once:

.. code-block:: Python

   # doc/conf.py
   extensions = [
     ...,
     "pyTooling.Sphinx",
   ]

.. rubric:: What it registers

* the **style roles**, together with the stylesheet they need - so the styling is a CSS file instead of a
  ``raw:: html`` block smuggled into every page - and the LaTeX package :file:`pyTooling.Sphinx.sty`, which strikes
  through and underlines in LaTeX:

  * ``:bolditalic:``, ``:underline:``, ``:strike:`` and ``:xlarge:`` - weight, decoration and size;
  * ``:red:``, ``:green:``, ``:blue:`` and ``:purple:`` - colour, each from a CSS custom property a project can
    redefine;
  * ``:deletion:`` and ``:addition:`` - the two a diff needs.

* the **code role**:

  * ``:pycode:`` - highlights inline Python.

* the **abbreviation roles**, named as in LaTeX' ``acro`` package:

  * ``:acs:``, ``:acl:`` and ``:acf:`` - an abbreviation, its long form, or both;
  * ``:acsp:``, ``:aclp:`` and ``:acfp:`` - their plurals.

* the **directives**:

  * :rst:dir:`condensed-class` - renders a class' public interface from its source;
  * :rst:dir:`dependency-table` - renders a project's dependencies from its requirements files, which
    :file:`conf.py` declares under ``pyTooling_Dependency_Requirements``;
  * :rst:dir:`xmlschema-graph` - draws an XML schema as a Graphviz graph. It sets up :mod:`sphinx.ext.graphviz`
    itself, and needs :mod:`xmlschema` only in a project that uses it.
  * :rst:dir:`shields` - renders a project's badges from shields.io, in rows, from the coordinates its options
    state: the GitHub repository, the PyPI package, the licenses, the workflow and the documentation's URL.
  * :rst:dir:`tree` - draws a hierarchy written as an indented list as a tree, each node foldable in HTML.
  * :rst:dir:`unicode-table` - lists icons with their Unicode names and code points, which HTML copies into the
    clipboard on a click; the script doing so is linked like the stylesheet.
  * :rst:dir:`abbreviations` - lists abbreviations, which the abbreviation roles refer to.

* the domain ``report`` - unit test, code coverage and documentation coverage reports as tables -, with the
  configuration values ``pyTooling_Unittest_Testsuites``, ``pyTooling_CodeCoverage_Packages`` and
  ``pyTooling_DocCoverage_Packages`` declaring the reports. Reading a report needs the extra ``reports``
  (pyEDAA.Reports), which is imported only then:

  * :rst:dir:`report:unittest-summary` - a unit test report, per testsuite and testcase; a report declared with
    ``pages`` gets a page per testsuite and testcase (:mod:`~pyTooling.Sphinx.UnittestPages`), which the roles
    ``:ts:`` and ``:tc:`` - also ``:report:ts:`` and ``:report:tc:`` - refer to;
  * :rst:dir:`report:code-coverage` and :rst:dir:`report:code-coverage-legend` - a code coverage report and its
    coverage levels;
  * :rst:dir:`report:doc-coverage` and :rst:dir:`report:doc-coverage-legend` - a package's documentation coverage
    and its coverage levels; a package declared with ``pages`` gets a page per package and module
    (:class:`~pyTooling.Sphinx.DocCoverage.DocCoverageReportPages`), which the role ``:doccov:`` refers to.

* the **nodes** the directives emit, listed in :data:`NODES` with their visitors per output format.

* the **external link icons** - in HTML, an icon behind each external link, chosen by its target, and the size behind
  each download -, with the configuration values ``pyTooling_ExternalLink_Icons``, ``pyTooling_ExternalLink_NewTab``,
  ``pyTooling_ExternalLink_Hosts``, ``pyTooling_ExternalLink_DownloadSizes``, ``pyTooling_ExternalLink_RemoteSizes``
  and ``pyTooling_ExternalLink_RemoteSizeTimeout`` (:mod:`~pyTooling.Sphinx.ExternalLink`).

Two classes aren't registered, because they are base-classes for a project's own directives:
:class:`~pyTooling.Sphinx.BaseDirective` offers typed option access and table construction
over the untyped mapping and the hand-assembled node trees docutils presents, and
:class:`~pyTooling.Sphinx.SchemaGraph.SchemaGraph` draws a schema file named as a directive's
argument, leaving only the reading of that schema to a derived class.

.. attention::

   This package requires **Python 3.12 or newer**, because it requires Sphinx 9.1 and Sphinx 9.1 does.

.. seealso::

   :mod:`pyTooling.Documentation`
      |rarr| The doc-string helpers, which need no Sphinx.
"""
__author__ =            "Patrick Lehmann"
__email__ =             "Paebbels@gmail.com"
__copyright__ =         "2026-2026, Patrick Lehmann"
__license__ =           "Apache License, Version 2.0"
__version__ =           "0.1.0rc4"
__keywords__ =          ["Sphinx", "Sphinx Extension", "Documentation", "Directive", "Role", "Domain", "docutils"]
__project_url__ =       "https://github.com/pyTooling/pyTooling.Sphinx"
__documentation_url__ = "https://pyTooling.github.io/pyTooling.Sphinx"
__issue_tracker_url__ = "https://GitHub.com/pyTooling/pyTooling.Sphinx/issues"

...

__all__ = [
	"STYLESHEET", "SCRIPT", "LATEX_PACKAGE", "SUBSTITUTIONS", "NODES", "LINE_ANCHOR", "REPORT_ROLES"
]

#: Name of the stylesheet, in :mod:`pyTooling.Sphinx.Resources`.
STYLESHEET = "pyTooling.css"

#: Name of the script, in :mod:`pyTooling.Sphinx.Resources`: it gives the copy buttons of the ``unicode-table``
#: directive their function.
SCRIPT = "pyTooling.js"

#: Name of the LaTeX package, whose file :file:`pyTooling.Sphinx.sty` is in :mod:`pyTooling.Sphinx.Resources`: it
#: defines the commands LaTeX writes for the style roles ``:strike:`` and ``:underline:``.
LATEX_PACKAGE = "pyTooling.Sphinx"

#: Substitutions that have to stay substitutions, because ``|br|`` is written as one in every project.
#:
#: ``|br|`` and ``|hr|`` delegate to the ``:br:`` and ``:hr:`` roles rather than writing HTML themselves, so they
#: reach every output format instead of only HTML - see :func:`~pyTooling.Sphinx.Roles.breakRole`.
SUBSTITUTIONS = """
.. |degree| unicode:: U+00B0
   :trim:

.. |br| replace:: :br:`.`

.. |hr| replace:: :hr:`.`
"""

#: The nodes the extension registers, each with its visitors per output format.
#:
#: A format without visitors of its own - e.g. LaTeX for the tree's nodes - writes a node with the visitors of its
#: base-class.
NODES: tuple[RegisteredNode, ...] = (
	{"name": "TreeItem",           "node": TreeItem,           "html": translateTreeItem},
	{"name": "TreeLabel",          "node": TreeLabel,          "html": translateTreeLabel},
	{"name": "TreeSeparator",      "node": TreeSeparator,      "html": translateTreeSeparator},
	{"name": "TreeDescription",    "node": TreeDescription,    "html": translateTreeDescription},
	{"name": "TreeLegend",         "node": TreeLegend,         "html": translateTreeLegend},
	{"name": "TreeLegendItem",     "node": TreeLegendItem,     "html": translateTreeLegendItem},
	{"name": "CopyButton",         "node": CopyButton,         "html": translateCopyButton},
	{"name": "Abbreviation",       "node": Abbreviation,       "html": translateAbbreviation},
	{"name": "Landscape",          "node": Landscape,          "html": translateLandscapeAsHTML,
	 "latex": translateLandscapeAsLaTeX},
	{"name": "CoverageListing",    "node": CoverageListing,    "html": translateCoverageListingAsHTML,
	 "latex": translateCoverageListingAsLaTeX},
	{"name": "DocCoverageListing", "node": DocCoverageListing, "html": translateDocCoverageListingAsHTML,
	 "latex": translateDocCoverageListingAsLaTeX},
	{"name": "Emoji",              "node": Emoji,              "html": translateEmoji},
	{"name": "TaskListCheckbox",   "node": TaskListCheckbox,   "html": translateTaskListCheckboxAsHTML,
	 "latex": translateTaskListCheckboxAsLaTeX},
	{"name": "LineBreak",          "node": LineBreak,          "html": translateLineBreakAsHTML,
	 "latex": translateLineBreakAsLaTeX},
	{"name": "ReportIndentation",  "node": ReportIndentation,  "html": translateReportIndentationAsHTML,
	 "latex": translateReportIndentationAsLaTeX},
)

_EnumType = TypeVar("_EnumType", bound=Enum)
"""Type of an enumeration read from a directive's options."""

@export
class SphinxExtensionError(ExtensionError, DocumentationError):
	"""
	Base-exception of all exceptions raised by :mod:`pyTooling.Sphinx`.

	It derives from **both** hierarchies on purpose: :exc:`~sphinx.errors.ExtensionError` is what Sphinx catches and
	reports with the position of the directive, and :exc:`~pyTooling.Documentation.DocumentationError` is what a
	caller of pyTooling catches. Neither would be enough alone.
	"""

@export
class ReportExtensionError(SphinxExtensionError):
	"""
	The exception raised by the ``report`` domain.

	It is raised e.g. for a mistake in the domain's configuration values or options.
	"""

@export
class ReportsPackageMissingError(ReportExtensionError):
	"""
	The exception raised when a report is read, but the optional packages of the extra ``reports`` aren't installed.

	The message names what was attempted and the packages it needs; a note says how to install them.
	"""

	def __init__(self, task: str, packages: str = "'pyEDAA.Reports'") -> None:
		"""
		Initialize the exception with what was attempted and the packages it needs.

		:param task:     What needs the packages, e.g. ``Reading a unit test report``.
		:param packages: Optional, the packages needed, quoted. Default: ``'pyEDAA.Reports'``.
		"""
		...

@export
class LegendStyle(Flag):
	"""
	How a legend directive of domain ``report`` lays out the coverage levels; a document writes the names with dashes.
	"""

	Default =    0     #: No style.
	Table =      1     #: A table.

	Horizontal = 1024  #: A column per level.
	Vertical =   2048  #: A row per level.

	horizontal_table = Table | Horizontal  #: A table with a column per level, written ``horizontal-table``.
	vertical_table =   Table | Vertical    #: A table with a row per level, written ``vertical-table``.

@export
def strip(option: str) -> str:
	"""
	Option converter removing surrounding whitespace.

	:param option: The option's value as it was written.
	:returns:      The value without surrounding whitespace.
	"""
	...

@export
def stripAndNormalize(option: str) -> str:
	"""
	Option converter removing surrounding whitespace and lowering the case.

	:param option: The option's value as it was written.
	:returns:      The value without surrounding whitespace, in lower case.
	"""
	...

@export
class BaseDirective(ObjectDescription[str]):
	"""
	Base-class for a directive, offering typed option access and table construction.

	A derived class sets :attr:`directiveName` - which is what the error messages name - and declares
	``option_spec`` as any directive does. What it gets in return is a ``_Parse***Option`` per type instead of
	reaching into :attr:`options` and validating by hand, and a ``_Create***TableHeader`` per table shape instead of
	assembling :class:`~docutils.nodes.tgroup`, :class:`~docutils.nodes.colspec`, :class:`~docutils.nodes.thead`
	and :class:`~docutils.nodes.row` in the right order.
	"""

	has_content =               False  #: A boolean; ``True`` if content is allowed.
	required_arguments =        0      #: Number of required directive arguments.
	optional_arguments =        0      #: Number of optional arguments after the required ones.
	final_argument_whitespace = False  #: A boolean; ``True`` if the last argument may contain spaces.
	option_spec =               {}     #: Mapping of option names to validator functions.

	directiveName: str  #: Name the directive is invoked by, used in every error message.

	def _ParseBooleanOption(self, optionName: str, default: Nullable[bool] = None) -> bool:
		"""
		Read an option written as ``yes``/``true`` or ``no``/``false``.

		:param optionName:             Name of the option to read.
		:param default:                Optional, the value to return when the option wasn't given.
		:returns:                      The option's value.
		:raises SphinxExtensionError:  If the option wasn't given and has no default.
		:raises SphinxExtensionError:  If the option's value is neither of the two accepted spellings.
		"""
		...

	def _ParseStringOption(self, optionName: str, default: Nullable[str] = None, regexp: str = "\\w+") -> str:
		"""
		Read an option that has to match a regular expression.

		The pattern defaults to one or more word characters.

		:param optionName:             Name of the option to read.
		:param default:                Optional, the value to return when the option wasn't given.
		:param regexp:                 Optional, the pattern the value has to match.
		:returns:                      The option's value.
		:raises SphinxExtensionError:  If the option wasn't given and has no default.
		:raises SphinxExtensionError:  If the option's value doesn't match the pattern.
		"""
		...

	def _ParseEnumOption(
		self,
		optionName: str,
		enumType: type[_EnumType],
		default: Nullable[_EnumType] = None
	) -> _EnumType:
		"""
		Read an option naming a member of an enumeration.

		The written value is lowered and its dashes become underscores, so ``horizontal-table`` in a document selects
		the ``horizontal_table`` member - a document reads in the spelling documents use, and the enumeration keeps
		the spelling Python uses.

		:param optionName:             Name of the option to read.
		:param enumType:               The enumeration whose members the value is looked up in.
		:param default:                Optional, the member to return when the option wasn't given.
		:returns:                      The named member of the enumeration.
		:raises SphinxExtensionError:  If the option wasn't given and has no default.
		:raises SphinxExtensionError:  If the value names no member of the enumeration.
		"""
		...

	def _CreateSingleRowTableHeader(
		self,
		columns: list[tuple[str, Nullable[int]]],
		identifier: str,
		classes: list[str]
	) -> nodes.tgroup:
		"""
		Create a table with a single header row.

		:param columns:    One ``(title, width)`` pair per column; a width of ``None`` leaves it to the writer.
		:param identifier: Identifier of the table.
		:param classes:    CSS classes to put on the table.
		:returns:          The table's column group, with the header row already in it.
		"""
		...

	def _CreateDoubleRowTableHeader(
		self,
		columns: list[tuple[str, Nullable[list[tuple[str, int]]], Nullable[int]]],
		identifier: str,
		classes: list[str]
	) -> nodes.tgroup:
		"""
		Create a table whose header spans two rows, so a column can group sub-columns.

		A column's ``subColumns`` is ``None`` when it spans both header rows, and otherwise holds the
		``(title, width)`` pairs below it.

		:param columns:    One ``(title, subColumns, width)`` triple per column.
		:param identifier: Identifier of the table.
		:param classes:    CSS classes to put on the table.
		:returns:          The table's column group, with both header rows already in it.
		"""
		...

	def _CreateRotatedTableHeader(
		self,
		columns: list[tuple[str, Nullable[list[str]]]],
		identifier: str,
		classes: list[str]
	) -> nodes.tgroup:
		"""
		Create a table whose header titles are rotated, for many narrow columns.

		:param columns:    One ``(title, classes)`` pair per column; the classes are put on the header cell.
		:param identifier: Identifier of the table.
		:param classes:    CSS classes to put on the table.
		:returns:          The table's column group, with the header row already in it.
		"""
		...

	def _internalError(
		self,
		container: nodes.container,
		location: str,
		message: str,
		exception: Exception
	) -> list[nodes.Node]:
		"""
		Report an exception a directive couldn't recover from, in the log **and** on the page.

		A directive that fails silently leaves a hole in the documentation that nobody notices. This puts the message
		where a reader sees it and the traceback where a maintainer does. The exception's notes - e.g. how to install a
		missing package - are logged below it.

		:param container: The container the message is put into.
		:param location:  Name of the logger, which is what the log line is attributed to.
		:param message:   What went wrong, in one sentence.
		:param exception: The exception that was caught.
		:returns:         The container, as the list a directive's ``run`` returns.
		"""
		...

@export
def installStaticFiles(sphinx: Sphinx) -> None:
	"""
	Call-back for Sphinx' ``builder-inited`` event, writing the stylesheet and the script into the build and linking
	them.

	A file is named by the hash of its content, so a browser re-reads it when it changes and re-uses it when it doesn't.
	Older copies are removed when the content changed.

	:param sphinx: The Sphinx application.
	"""
	...

@export
def installLaTeXPackage(sphinx: Sphinx) -> None:
	"""
	Call-back for Sphinx' ``builder-inited`` event, writing the LaTeX package :data:`LATEX_PACKAGE` into the build of a
	LaTeX builder, where the document's ``\\usepackage`` finds it.

	:param sphinx: The Sphinx application.
	"""
	...

@export
def extendProlog(sphinx: Sphinx, config: Any) -> None:
	"""
	Call-back for Sphinx' ``config-inited`` event, appending the shared substitutions to ``rst_prolog``.

	A role can be registered; a **substitution** cannot - ``|br|`` is substitution syntax, and every project writes
	it that way already. Appending them here is what lets a project delete them from its own prolog without changing
	a single document.

	:param sphinx: The Sphinx application.
	:param config: The configuration, after :file:`conf.py` was read.
	"""
	...

@export
def setLaTeXDefaults(sphinx: Sphinx, config: Config) -> None:
	"""
	Call-back for Sphinx' ``config-inited`` event, setting LaTeX defaults, unless :file:`conf.py` sets them.

	* ``latex_table_style``: ``["booktabs"]``, without Sphinx' default ``colorrows``.
	* ``latex_elements["maxlistdepth"]``: ``"10"`` nested lists, e.g. a :rst:dir:`tree` with more than 4 levels.

	:param sphinx: The Sphinx application.
	:param config: The configuration, after :file:`conf.py` was read.
	"""
	...

@export
class ReportEntry(NamedTuple):
	"""
	An object of a report, which has a page of its own - a testcase, a source file, ...: where it is, and its names.
	"""

	docName:   str              #: Name of the generated document showing the object.
	reportID:  str              #: Identifier of the report in its configuration value.
	path:      tuple[str, ...]  #: Names of the objects from the report's root down to this object's own name.
	separator: str              #: Separator of the names in a qualified name, e.g. ``.`` or ``/``.
	title:     Nullable[str]    #: Title of the object written for a reader, if the report has one.

	@readonly
	def Name(self) -> str:
		"""
		Read-only property to return the object's own name, the last element of :attr:`path`.

		:returns: The name.
		"""
		...

	@readonly
	def QualifiedName(self) -> str:
		"""
		Read-only property to return the qualified name: the names of :attr:`path` joined by :attr:`separator`.

		:returns: The qualified name, e.g. ``pytest.tests.unit.Arithmetic.Addition.test_Positive``.
		"""
		...

	def Matches(self, name: str) -> bool:
		"""
		Check whether a name is the qualified name or a suffix of it, which starts at an element of :attr:`path`.

		:param name: The name as written in a reference, without a report ID.
		:returns:    ``True`` if the name is the qualified name or one of its suffixes.
		"""
		...

@export
class ReportRoleDefinition(NamedTuple):
	"""
	What a role of domain ``report`` refers to: a kind of object of the reports declared in a configuration value.
	"""

	objectType:  str           #: The object type, as listed by the domain, e.g. ``testcase``.
	configValue: str           #: The configuration value declaring the reports; its first report is the default one.
	reports:     str           #: The reports, as a warning names them, e.g. ``unit test reports``.
	lineAnchors: bool = False  #: Whether a target may end in ``#<line number>``, linking to the line on the page.

#: The line number a target of a role with line anchors may end in, e.g. ``#12`` of ``src/Counter.vhdl#12``.
LINE_ANCHOR = re_compile(r"#(\d+)$")

#: The roles referring to the objects of reports with pages, by role name.
REPORT_ROLES = {
	"tc":     ReportRoleDefinition("testcase",  "pyTooling_Unittest_Testsuites",   "unit test reports"),
	"ts":     ReportRoleDefinition("testsuite", "pyTooling_Unittest_Testsuites",   "unit test reports"),
	"cov":    ReportRoleDefinition("source",    "pyTooling_CodeCoverage_Packages", "code coverage reports", True),
	"doccov": ReportRoleDefinition("module",    "pyTooling_DocCoverage_Packages",  "documentation coverage reports"),
}

@export
class ReportRole(XRefRole):
	"""
	A role of domain ``report`` referring to an object of a report with pages.

	Role ``tc`` refers to a testcase, ``ts`` to a testsuite.

	Sphinx registers a role outside a domain without one, so the reference would be resolved by nobody; this role puts
	domain ``report`` on the reference, and uses its name as the reference's type. So it works as ``:report:tc:`` and
	as the global ``:tc:``.
	"""

	def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
		"""
		Create the reference, or only the text if the role is written with ``!``.

		:returns: The nodes and messages a role returns.
		"""
		...

@export
class ReportDomain(Domain):
	"""
	The Sphinx domain ``report``, integrating unit test, code coverage and documentation coverage reports.

	Its directives are registered by :func:`setup`, and read their reports from the files declared in :file:`conf.py`.

	A report with generated pages contributes an object per page - e.g. a unit test report its testsuites and
	testcases -, which the roles of :data:`REPORT_ROLES` refer to, e.g. ``:report:tc:``, also registered as ``:tc:``. A
	reference names an object by its qualified name, or by a suffix of it, optionally preceded by the report's
	identifier and a colon; without one, the first report of the role's configuration value is meant.
	"""

	name =         "report"  #: Name of the domain, the prefix of its directives.
	label =        "rpt"     #: Name of the domain, as displayed.
	data_version = 2         #: Version of the domain data's layout; a pickled environment of another version is dropped.

	object_types = {
		definition.objectType: ObjType(definition.objectType, roleName) for roleName, definition in REPORT_ROLES.items()
	}  #: The objects: per role, the objects of the reports with generated pages.
	initial_data: dict[str, Any] = {
		roleName: {} for roleName in REPORT_ROLES
	}  #: The data of an empty documentation: per role, no object.
	roles = {
		roleName: ReportRole(innernodeclass=nodes.inline, warn_dangling=True) for roleName in REPORT_ROLES
	}  #: The roles, also registered without the domain's prefix.
	dangling_warnings = {
		roleName: f"{definition.objectType} '%(target)s' not found in the {definition.reports}"
		for roleName, definition in REPORT_ROLES.items()
	}  #: The warning for a reference to an unknown object, per role.

	def AddEntry(self, roleName: str, entry: ReportEntry) -> None:
		"""
		Register an object, which has a generated page.

		:param roleName: The role referring to the object, e.g. ``tc`` for a testcase.
		:param entry:    The object.
		"""
		...

	def FindEntries(self, roleName: str, target: str) -> list[ReportEntry]:
		"""
		Find the objects a reference's target names.

		A target is ``[<report ID>:]<name>``. If the part before the first colon isn't the identifier of a report, the
		whole target is the name in the default report - the first one of the role's configuration value -, as e.g. a
		parametrized testcase's name may contain a colon. A name is a qualified name or a suffix of one (see
		:meth:`ReportEntry.Matches`); an exact qualified name wins over suffixes.

		:param roleName: The role referring to the object, e.g. ``tc`` for a testcase.
		:param target:   The reference's target.
		:returns:        The matching entries: none, one, or several if the name is ambiguous.
		"""
		...

	def clear_doc(self, docname: str) -> None:
		"""
		Forget the objects of a document, before it is generated again.

		:param docname: Name of the document.
		"""
		...

	def merge_domaindata(self, docnames: Iterable[str], otherdata: dict[str, Any]) -> None:
		"""
		Take over the objects a parallel reader collected for its documents.

		:param docnames:  Names of the documents the other reader read.
		:param otherdata: The other reader's domain data.
		"""
		...

	def resolve_xref(
		self,
		env: BuildEnvironment,
		fromdocname: str,
		builder: Builder,
		typ: str,
		target: str,
		node: pending_xref,
		contnode: nodes.Element
	) -> Nullable[nodes.Element]:
		"""
		Resolve a reference to an object of a report into a link to its page.

		The link shows the object's name, or the title written in the role; in HTML, its title written for a reader - if
		the report has one - is shown on hover. An ambiguous name is warned about and shown as text.

		:param env:         The build environment.
		:param fromdocname: Name of the document holding the reference.
		:param builder:     The builder writing the documents.
		:param typ:         The role's name, e.g. ``tc``.
		:param target:      The object referred to.
		:param node:        The reference.
		:param contnode:    The reference's text.
		:returns:           The link, the text if the name is ambiguous or the builder doesn't write the page, or
		                    ``None`` if nothing matches.
		"""
		...

	def resolve_any_xref(
		self,
		env: BuildEnvironment,
		fromdocname: str,
		builder: Builder,
		target: str,
		node: pending_xref,
		contnode: nodes.Element
	) -> list[tuple[str, nodes.reference]]:
		"""
		Resolve a reference of role ``:any:`` to an object of a report with an unambiguous name.

		:param env:         The build environment.
		:param fromdocname: Name of the document holding the reference.
		:param builder:     The builder writing the documents.
		:param target:      The text referred to.
		:param node:        The reference.
		:param contnode:    The reference's text.
		:returns:           A role and link per kind of object the text names unambiguously.
		"""
		...

	def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]:
		"""
		Name the objects of the reports, for the search and for other documentations referring to them.

		An object's name is ``<report ID>:<qualified name>``. A testcase gets a lower search priority than a testsuite,
		as a report may have thousands of them.

		:returns: A tuple per object: name, display name, type, document, anchor and search priority.
		"""
		...

@export
def checkReportConfiguration(sphinx: Sphinx, config: Config) -> None:
	"""
	Call-back for Sphinx' ``config-inited`` event, checking the reports' configuration values and loading their settings.

	A mistake is logged as an error rather than stopping the build; a directive naming that report fails on its own.

	:param sphinx: The Sphinx application.
	:param config: The configuration, after :file:`conf.py` was read.
	"""
	...

@export
def readReports(sphinx: Sphinx) -> None:
	"""
	Call-back for Sphinx' ``builder-inited`` event, reading the report files, analyzing the documented packages, and
	registering the reports' pages.

	:param sphinx: The Sphinx application.
	"""
	...

@export
def setup(sphinx: Sphinx) -> dict[str, Any]:
	"""
	Register the roles, the nodes, the directives and the domain ``report`` with Sphinx.

	The modules are imported here rather than with the package, and none of them imports an optional dependency at
	module level - e.g. pyEDAA.Reports is imported only when a report is read - so the extension works without them.

	:param sphinx: The Sphinx application to register with.
	:returns:      The extension's metadata.
	"""
	...