sphinx_reports

A Sphinx domain providing directives to add reports to the Sphinx-based documentation.

Supported reports:

• Unittest Summary Report

• Documentation Coverage Report

• Code Coverage Report

• Dependencies

Submodules

• sphinx_reports.Adapter
• sphinx_reports.CodeCoverage
• sphinx_reports.Common
• sphinx_reports.DataModel
• sphinx_reports.Dependency
• sphinx_reports.DocCoverage
• sphinx_reports.HTML
• sphinx_reports.LaTeX
• sphinx_reports.Node
• sphinx_reports.Sphinx
• sphinx_reports.Unittest
• sphinx_reports.Workaround
• sphinx_reports.static

Functions

• setup(): Extension setup function registering the report domain in Sphinx.

Classes

• RegisteredNode: Type information for an entry in ReportDomain.nodes.

• ReportDomain: A Sphinx extension providing a report domain to integrate reports and summaries into a Sphinx-based documentation.

---

Functions

sphinx_reports.setup(sphinxApplication)

Extension setup function registering the report domain in Sphinx.

It will execute these steps:

• register domains, directives and roles.

• connect events (register callbacks)

• register configuration variables for conf.py

Parameters:

sphinxApplication (<module ‘sphinx_reports.Sphinx’ from ‘/home/runner/work/sphinx-reports/sphinx-reports/sphinx_reports/Sphinx.py’>) – The Sphinx application.

Return type:

setup_ReturnType

Returns:

Dictionary containing the extension version and some properties.

---

Classes

class sphinx_reports.RegisteredNode

Type information for an entry in ReportDomain.nodes.

Inheritance

name: str

Name of the new docutils node to register.

node: Type[Element]

The new node class to register.

html: Tuple[visitFunc, departFunc]

A tuple of visit and depart functions rendering the new node in case of HTML output.

latex: Tuple[visitFunc, departFunc]

A tuple of visit and depart functions rendering the new node in case of LaTeX output.

classmethod __class_getitem__(object, /)

See PEP 585

__contains__(key, /)

True if the dictionary has the specified key, else False.

__delitem__(key, /)

Delete self[key].

__eq__(value, /)

Return self==value.

__ge__(value, /)

Return self>=value.

__getitem__(key, /)

Return self[key].

__gt__(value, /)

Return self>value.

__init__(*args, **kwargs)

__ior__(value, /)

Return self|=value.

__iter__()

Implement iter(self).

__le__(value, /)

Return self<=value.

__len__()

Return len(self).

__lt__(value, /)

Return self<value.

__ne__(value, /)

Return self!=value.

classmethod __new__(*args, **kwargs)

__or__(value, /)

Return self|value.

__repr__()

Return repr(self).

__reversed__()

Return a reverse iterator over the dict keys.

__ror__(value, /)

Return value|self.

__setitem__(key, value, /)

Set self[key] to value.

__sizeof__()

Return the size of the dict in memory, in bytes.

clear()

Remove all items from the dict.

copy()

Return a shallow copy of the dict.

classmethod fromkeys(iterable, value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items()

Return a set-like object providing a view on the dict’s items.

keys()

Return a set-like object providing a view on the dict’s keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values()

Return an object providing a view on the dict’s values.

class sphinx_reports.ReportDomain(env)

A Sphinx extension providing a report domain to integrate reports and summaries into a Sphinx-based documentation.

New directives:

• report:code-coverage

• report:code-coverage-legend

• report:doc-coverage

• report:doc-coverage-legend

• report:dependency-table

• report:unittest-summary

New roles:

• None

New indices:

• None

Configuration variables

All configuration variables in conf.py are prefixed with report_*:

• report_codecov_packages

• report_doccov_packages

• report_unittest_testsuites

Inheritance

Parameters:

env (BuildEnvironment)

name: ClassVar[str] = 'report'

The name of this domain

label: ClassVar[str] = 'rpt'

The label of this domain

dependencies: List[str] = []

A list of other extensions this domain depends on.

directives: ClassVar[dict[str, type[Directive]]] = {'code-coverage': <class 'sphinx_reports.CodeCoverage.CodeCoverage'>, 'code-coverage-legend': <class 'sphinx_reports.CodeCoverage.CodeCoverageLegend'>, 'dependency-table': <class 'sphinx_reports.Dependency.DependencyTable'>, 'doc-coverage': <class 'sphinx_reports.DocCoverage.DocStrCoverage'>, 'doc-coverage-legend': <class 'sphinx_reports.DocCoverage.DocCoverageLegend'>, 'module-coverage': <class 'sphinx_reports.CodeCoverage.ModuleCoverage'>, 'unittest-summary': <class 'sphinx_reports.Unittest.UnittestSummary'>}

A dictionary of all directives in this domain.

roles: ClassVar[dict[str, RoleFunction | XRefRole]] = {}

A dictionary of all roles in this domain.

indices: ClassVar[list[type[Index]]] = []

A list of all indices in this domain.

configValues: Dict[str, Tuple[Any, str, Any]] = {'codecov_levels': ({'default': {'error': {'class': 'report-cov-error', 'desc': 'internal error'}, 10: {'class': 'report-cov-below10', 'desc': 'almost unused'}, 100: {'class': 'report-cov-below100', 'desc': 'excellently used'}, 20: {'class': 'report-cov-below20', 'desc': 'almost unused'}, 30: {'class': 'report-cov-below30', 'desc': 'almost unused'}, 40: {'class': 'report-cov-below40', 'desc': 'poorly used'}, 50: {'class': 'report-cov-below50', 'desc': 'poorly used'}, 60: {'class': 'report-cov-below60', 'desc': 'somehow used'}, 70: {'class': 'report-cov-below70', 'desc': 'somehow used'}, 80: {'class': 'report-cov-below80', 'desc': 'somehow used'}, 85: {'class': 'report-cov-below85', 'desc': 'well used'}, 90: {'class': 'report-cov-below90', 'desc': 'well used'}, 95: {'class': 'report-cov-below95', 'desc': 'well used'}}}, 'env', typing.Dict), 'codecov_packages': ({}, 'env', typing.Dict), 'doccov_levels': ({'default': {'error': {'class': 'report-cov-error', 'desc': 'internal error'}, 10: {'class': 'report-cov-below10', 'desc': 'almost undocumented'}, 100: {'class': 'report-cov-below100', 'desc': 'excellent documented'}, 20: {'class': 'report-cov-below20', 'desc': 'almost undocumented'}, 30: {'class': 'report-cov-below30', 'desc': 'almost undocumented'}, 40: {'class': 'report-cov-below40', 'desc': 'poorly documented'}, 50: {'class': 'report-cov-below50', 'desc': 'poorly documented'}, 60: {'class': 'report-cov-below60', 'desc': 'roughly documented'}, 70: {'class': 'report-cov-below70', 'desc': 'roughly documented'}, 80: {'class': 'report-cov-below80', 'desc': 'roughly documented'}, 85: {'class': 'report-cov-below85', 'desc': 'well documented'}, 90: {'class': 'report-cov-below90', 'desc': 'well documented'}, 95: {'class': 'report-cov-below95', 'desc': 'well documented'}}}, 'env', typing.Dict), 'doccov_packages': ({}, 'env', typing.Dict), 'unittest_testsuites': ({}, 'env', typing.Dict)}

A dictionary of all configuration values used by this domain. (name: (default, rebuilt, type))

initial_data: ClassVar[dict[str, Any]] = {}

A dictionary of all global data fields used by this domain.

static CheckConfigurationVariables(sphinxApplication, config)

Call back for Sphinx config-inited event.

This callback will verify configuration variables used by that domain.

See also

Sphinx builder-inited event

See https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events

Parameters:

• sphinxApplication (<module ‘sphinx_reports.Sphinx’ from ‘/home/runner/work/sphinx-reports/sphinx-reports/sphinx_reports/Sphinx.py’>) – The Sphinx application.

• config (Config) – Sphinx configuration parsed from conf.py.

Return type:

None

static AddCSSFiles(sphinxApplication)

Call back for Sphinx builder-inited event.

This callback will copy the CSS file(s) to the build directory.

See also

Sphinx builder-inited event

See https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events

Parameters:

sphinxApplication (<module ‘sphinx_reports.Sphinx’ from ‘/home/runner/work/sphinx-reports/sphinx-reports/sphinx_reports/Sphinx.py’>) – The Sphinx application.

Return type:

None

static ReadReports(sphinxApplication)

Call back for Sphinx builder-inited event.

This callback will read the linked report files

See also

Sphinx builder-inited event

See https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events

Parameters:

sphinxApplication (<module ‘sphinx_reports.Sphinx’ from ‘/home/runner/work/sphinx-reports/sphinx-reports/sphinx_reports/Sphinx.py’>) – The Sphinx application.

Return type:

None

callbacks: Dict[str, List[Callable]] = {'builder-inited': [<staticmethod(<function ReportDomain.AddCSSFiles>)>, <staticmethod(<function ReportDomain.ReadReports>)>], 'config-inited': [<staticmethod(<function ReportDomain.CheckConfigurationVariables>)>]}

A dictionary of all events/callbacks <https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events>`__ used by this domain.

resolve_xref(env, fromdocname, builder, typ, target, node, contnode)

Resolve the pending_xref node with the given typ and target.

This method should return a new node, to replace the xref node, containing the contnode which is the markup content of the cross-reference.

If no resolution can be found, None can be returned; the xref node will then given to the :event:`missing-reference` event, and if that yields no resolution, replaced by contnode.

The method can also raise sphinx.environment.NoUri to suppress the :event:`missing-reference` event being emitted.

Return type:

Element | None

Parameters:

• env (BuildEnvironment)

• fromdocname (str)

• builder (Builder)

• typ (str)

• target (str)

• node (pending_xref)

• contnode (Element)

__init__(env)

Parameters:

env (BuildEnvironment)

Return type:

None

add_object_type(name, objtype)

Add an object type.

Return type:

None

Parameters:

• name (str)

• objtype (ObjType)

check_consistency()

Do consistency checks (experimental).

Return type:

None

clear_doc(docname)

Remove traces of a document in the domain-specific inventories.

Return type:

None

Parameters:

docname (str)

dangling_warnings: ClassVar[dict[str, str]] = {}

role name -> a warning message if reference is missing

data_version: ClassVar[int] = 0

data version, bump this when the format of self.data changes

directive(name)

Return a directive adapter class that always gives the registered directive its full name (‘domain:name’) as self.name.

Return type:

type[Directive] | None

Parameters:

name (str)

enumerable_nodes: ClassVar[dict[type[Node], tuple[str, TitleGetter | None]]] = {}

node_class -> (enum_node_type, title_getter)

get_enumerable_node_type(node)

Get type of enumerable nodes (experimental).

Return type:

str | None

Parameters:

node (Node)

get_full_qualified_name(node)

Return full qualified name for given node.

Return type:

str | None

Parameters:

node (Element)

get_objects()

Return an iterable of “object descriptions”.

Object descriptions are tuples with six items:

Return type:

Iterable[tuple[str, str, str, str, str, int]]

name

Fully qualified name.

dispname

Name to display when searching/linking.

type

Object type, a key in self.object_types.

docname

The document where it is to be found.

anchor

The anchor name for the object.

priority

How “important” the object is (determines placement in search results). One of:

1

Default priority (placed before full-text matches).

0

Object is important (placed before default-priority objects).

2

Object is unimportant (placed after full-text matches).

-1

Object should not show up in search at all.

get_type_name(type, primary=False)

Return full name for given ObjType.

Return type:

str

Parameters:

• type (ObjType)

• primary (bool)

merge_domaindata(docnames, otherdata)

Merge in data regarding docnames from a different domaindata inventory (coming from a subprocess in parallel builds).

Return type:

None

Parameters:

• docnames (Set[str])

• otherdata (dict[str, Any])

object_types: ClassVar[dict[str, ObjType]] = {}

type (usually directive) name -> ObjType instance

process_doc(env, docname, document)

Process a document after it is read by the environment.

Return type:

None

Parameters:

• env (BuildEnvironment)

• docname (str)

• document (document)

process_field_xref(pnode)

Process a pending xref created in a doc field. For example, attach information about the current scope.

Return type:

None

Parameters:

pnode (pending_xref)

resolve_any_xref(env, fromdocname, builder, target, node, contnode)

Resolve the pending_xref node with the given target.

The reference comes from an “any” or similar role, which means that we don’t know the type. Otherwise, the arguments are the same as for resolve_xref().

The method must return a list (potentially empty) of tuples ('domain:role', newnode), where 'domain:role' is the name of a role that could have created the same reference, e.g. 'py:func'. newnode is what resolve_xref() would return.

Added in version 1.3.

Return type:

list[tuple[str, reference]]

Parameters:

• env (BuildEnvironment)

• fromdocname (str)

• builder (Builder)

• target (str)

• node (pending_xref)

• contnode (Element)

role(name)

Return a role adapter function that always gives the registered role its full name (‘domain:name’) as the first argument.

Return type:

RoleFunction | None

Parameters:

name (str)

setup()

Set up domain object.

Return type:

None

data: dict[str, Any]

data value