sphinx_reports

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

Supported reports:

• Documentation Coverage

• Code Coverage

• Unit Test Summary

• Dependencies

Submodules

• sphinx_reports.Adapter
• sphinx_reports.CodeCoverage
• sphinx_reports.Common
• sphinx_reports.DataModel
• sphinx_reports.DocCoverage
• sphinx_reports.Sphinx
• sphinx_reports.Unittest
• sphinx_reports.static

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)

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)

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

New directives:

• doc-coverage

New roles:

• None

New indices:

• None

Configuration variables

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

• report_unittest_testsuites

• report_codecov_packages

• report_doccov_packages

Inheritance

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.

class CodeCoverage(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

This directive will be replaced by a table representing code coverage.

__class_getitem__()

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo[T]: ….

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

__init_subclass__()

Function to initialize subclasses.

_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Return type:

tuple[str, ...]

Parameters:

sig_node (desc_signature)

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Return type:

str

Parameters:

sig_node (desc_signature)

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

add_target_and_index(name, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Return type:

None

Parameters:

• name (ObjDescT)

• sig (str)

• signode (desc_signature)

after_content()

Called after parsing content. Used to reset information about the current directive context on the build environment.

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Called before parsing content. Used to set information about the current directive context on the build environment.

Return type:

None

property config: Config

Reference to the Config object.

configValues: Dict[str, Tuple[Any, str, Any]] = {'codecov_packages': ({}, 'env', typing.Dict)}

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

directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

final_argument_whitespace = False

A boolean, indicating if the final argument may contain whitespace.

get_location()

Get current location info for logging.

Return type:

str

get_signatures()

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Return type:

tuple[str, int]

handle_signature(sig, signode)

Parse the signature sig into individual nodes and append them to signode. If ValueError is raised, parsing is aborted and the whole sig is put into a single desc_name node.

The return value should be a value that identifies the object. It is passed to add_target_and_index() unchanged, and otherwise only used to skip duplicates.

Return type:

TypeVar(ObjDescT)

Parameters:

• sig (str)

• signode (desc_signature)

has_content: bool = False

A boolean; True if content is allowed.

Client code must handle the case where content is required but not supplied (an empty content list will be supplied).

option_spec: ClassVar[OptionSpec] = {'legend': <function strip>, 'packageid': <function strip>}

Mapping of option names to validator functions.

A dictionary, mapping known option names to conversion functions such as int or float (default: {}, no options). Several conversion functions are defined in the directives/__init__.py module.

Option conversion functions take a single parameter, the option argument (a string or None), validate it and/or convert it to the appropriate form. Conversion functions may raise ValueError and TypeError exceptions.

optional_arguments = 2

Number of optional arguments after the required arguments.

required_arguments = 0

Number of required directive arguments.

run()

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does: :rtype: List[Node]

• find out if called as a domain-specific directive, set self.domain

• create a desc node to fit all description inside

• parse standard options, currently no-index

• create an index node if needed as self.indexnode

• parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

• add index entries using self.add_target_and_index()

• parse the content and handle doc fields in it

Return type:

List[Node]

set_source_info(node)

Set source and line number to the node.

Return type:

None

Parameters:

node (Node)

transform_content(contentnode)

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

Return type:

None

Parameters:

contentnode (desc_content)

class DocStrCoverage(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

__class_getitem__()

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo[T]: ….

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

__init_subclass__()

Function to initialize subclasses.

_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Return type:

tuple[str, ...]

Parameters:

sig_node (desc_signature)

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Return type:

str

Parameters:

sig_node (desc_signature)

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

add_target_and_index(name, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Return type:

None

Parameters:

• name (ObjDescT)

• sig (str)

• signode (desc_signature)

after_content()

Called after parsing content. Used to reset information about the current directive context on the build environment.

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Called before parsing content. Used to set information about the current directive context on the build environment.

Return type:

None

property config: Config

Reference to the Config object.

configValues: Dict[str, Tuple[Any, str, Any]] = {'doccov_packages': ({}, 'env', typing.Dict)}

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

directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

final_argument_whitespace = False

A boolean, indicating if the final argument may contain whitespace.

get_location()

Get current location info for logging.

Return type:

str

get_signatures()

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Return type:

tuple[str, int]

handle_signature(sig, signode)

Parse the signature sig into individual nodes and append them to signode. If ValueError is raised, parsing is aborted and the whole sig is put into a single desc_name node.

The return value should be a value that identifies the object. It is passed to add_target_and_index() unchanged, and otherwise only used to skip duplicates.

Return type:

TypeVar(ObjDescT)

Parameters:

• sig (str)

• signode (desc_signature)

has_content: bool = False

A boolean; True if content is allowed.

Client code must handle the case where content is required but not supplied (an empty content list will be supplied).

option_spec: ClassVar[OptionSpec] = {'legend': <function strip>, 'packageid': <function strip>}

Mapping of option names to validator functions.

A dictionary, mapping known option names to conversion functions such as int or float (default: {}, no options). Several conversion functions are defined in the directives/__init__.py module.

Option conversion functions take a single parameter, the option argument (a string or None), validate it and/or convert it to the appropriate form. Conversion functions may raise ValueError and TypeError exceptions.

optional_arguments = 2

Number of optional arguments after the required arguments.

required_arguments = 0

Number of required directive arguments.

run()

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does: :rtype: List[Node]

• find out if called as a domain-specific directive, set self.domain

• create a desc node to fit all description inside

• parse standard options, currently no-index

• create an index node if needed as self.indexnode

• parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

• add index entries using self.add_target_and_index()

• parse the content and handle doc fields in it

Return type:

List[Node]

set_source_info(node)

Set source and line number to the node.

Return type:

None

Parameters:

node (Node)

transform_content(contentnode)

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

Return type:

None

Parameters:

contentnode (desc_content)

class UnittestSummary(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

This directive will be replaced by a table representing unit test results.

__class_getitem__()

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo[T]: ….

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

__init_subclass__()

Function to initialize subclasses.

_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Return type:

tuple[str, ...]

Parameters:

sig_node (desc_signature)

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Return type:

str

Parameters:

sig_node (desc_signature)

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

add_target_and_index(name, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Return type:

None

Parameters:

• name (ObjDescT)

• sig (str)

• signode (desc_signature)

after_content()

Called after parsing content. Used to reset information about the current directive context on the build environment.

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Called before parsing content. Used to set information about the current directive context on the build environment.

Return type:

None

property config: Config

Reference to the Config object.

configValues: Dict[str, Tuple[Any, str, Any]] = {'unittest_testsuites': ({}, 'env', typing.Dict)}

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

directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

final_argument_whitespace = False

A boolean, indicating if the final argument may contain whitespace.

get_location()

Get current location info for logging.

Return type:

str

get_signatures()

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Return type:

tuple[str, int]

handle_signature(sig, signode)

Parse the signature sig into individual nodes and append them to signode. If ValueError is raised, parsing is aborted and the whole sig is put into a single desc_name node.

The return value should be a value that identifies the object. It is passed to add_target_and_index() unchanged, and otherwise only used to skip duplicates.

Return type:

TypeVar(ObjDescT)

Parameters:

• sig (str)

• signode (desc_signature)

has_content: bool = False

A boolean; True if content is allowed.

Client code must handle the case where content is required but not supplied (an empty content list will be supplied).

option_spec: ClassVar[OptionSpec] = {'reportid': <function strip>}

Mapping of option names to validator functions.

A dictionary, mapping known option names to conversion functions such as int or float (default: {}, no options). Several conversion functions are defined in the directives/__init__.py module.

Option conversion functions take a single parameter, the option argument (a string or None), validate it and/or convert it to the appropriate form. Conversion functions may raise ValueError and TypeError exceptions.

optional_arguments = 1

Number of optional arguments after the required arguments.

required_arguments = 0

Number of required directive arguments.

run()

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does: :rtype: List[Node]

• find out if called as a domain-specific directive, set self.domain

• create a desc node to fit all description inside

• parse standard options, currently no-index

• create an index node if needed as self.indexnode

• parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

• add index entries using self.add_target_and_index()

• parse the content and handle doc fields in it

Return type:

List[Node]

set_source_info(node)

Set source and line number to the node.

Return type:

None

Parameters:

node (Node)

transform_content(contentnode)

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

Return type:

None

Parameters:

contentnode (desc_content)

directives: dict[str, type[Directive]] = {'code-coverage': <class 'sphinx_reports.CodeCoverage.CodeCoverage'>, 'dependecy': <class 'sphinx_reports.DocCoverage.DocStrCoverage'>, 'doc-coverage': <class 'sphinx_reports.DocCoverage.DocStrCoverage'>, '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_packages': ({}, '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 = {'reports': {}}

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

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 configuration variable vhdl_designs and parse the found VHDL source 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>)>]}

A dictionary of all events/callbacks 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 :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:

Optional[Callable]

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:

• docnames (list[str])

• otherdata (dict[str, Any])

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:

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

Parameters:

name (str)

setup()

Set up domain object.

Return type:

None

data: dict

data value