sphinx_reports

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

Supported reports:

Submodules

Functions

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

Classes

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

Functions

sphinx_reports.setup(sphinxApplication)[source]

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.ReportDomain(env)[source]

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

New directives:

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

Inheritance diagram of ReportDomain

Parameters:

env (BuildEnvironment)

name = 'report'

The name of this domain

label = 'rpt'

The label of this domain

dependencies: List[str] = []

A list of other extensions this domain depends on.

directives: 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: dict[str, RoleFunction | XRefRole] = {}

A dictionary of all roles in this domain.

indices: 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'}, 100: {'class': 'report-cov-below100', 'desc': 'excellently used'}, 30: {'class': 'report-cov-below30', 'desc': 'almost unused'}, 50: {'class': 'report-cov-below50', 'desc': 'poorly used'}, 80: {'class': 'report-cov-below80', 'desc': 'somehow used'}, 90: {'class': 'report-cov-below90', 'desc': 'well used'}}}, 'env', typing.Dict), 'codecov_packages': ({}, 'env', typing.Dict), 'doccov_levels': ({'default': {'error': {'class': 'report-cov-error', 'desc': 'internal error'}, 100: {'class': 'report-cov-below100', 'desc': 'excellent documented'}, 30: {'class': 'report-cov-below30', 'desc': 'almost undocumented'}, 50: {'class': 'report-cov-below50', 'desc': 'poorly documented'}, 80: {'class': 'report-cov-below80', 'desc': 'roughly documented'}, 90: {'class': 'report-cov-below90', '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: dict = {}

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

static CheckConfigurationVariables(sphinxApplication, config)[source]

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)[source]

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)[source]

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)[source]

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 :rtype: Optional[Element]

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.

Parameters:

  • env (BuildEnvironment)

  • fromdocname (str)

  • builder (Builder)

  • typ (str)

  • target (str)

  • node (pending_xref)

  • contnode (Element)

Return type:

Element | None

__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: dict[str, str] = {}

role name -> a warning message if reference is missing

data_version = 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:

Callable | None

Parameters:

name (str)

enumerable_nodes: 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:
object_types: 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. :rtype: list[tuple[str, Element]]

Added in version 1.3.

Parameters:

  • env (BuildEnvironment)

  • fromdocname (str)

  • builder (Builder)

  • target (str)

  • node (pending_xref)

  • contnode (Element)

Return type:

list[tuple[str, 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:

Callable[[str, str, str, int, Inliner, dict[str, Any], Sequence[str]], tuple[list[Node], list[system_message]]] | None

Parameters:

name (str)

setup()

Set up domain object.

Return type:

None

data: dict[str, Any]

data value