sphinx_reports.CodeCoverage

Report code coverage as Sphinx documentation page(s).

Classes

  • CodeCoverageBase: Directive to describe a class, function or similar object. Not used

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

  • CodeCoverageLegend: This directive will be replaced by a legend table representing coverage levels.

  • ModuleCoverage: This directive will be replaced by highlighted source code.

Classes

class sphinx_reports.CodeCoverage.CodeCoverageBase(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Inheritance

Inheritance diagram of CodeCoverageBase

option_spec: ClassVar[OptionSpec] = {'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.

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)}

A dictionary of all configuration values used by code coverage directives.

classmethod CheckConfiguration(sphinxApplication, sphinxConfiguration)[source]

Check configuration fields and load necessary values.

Parameters:

  • sphinxApplication (Sphinx) – Sphinx application instance.

  • sphinxConfiguration (Config) – Sphinx configuration instance.

Return type:

None

classmethod ReadReports(sphinxApplication)[source]

Read code coverage report files.

Parameters:

sphinxApplication (Sphinx) – Sphinx application instance.

Return type:

None

__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.

Added in version 1.8.

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.

Added in version 1.8.

final_argument_whitespace = False

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

get_location()

Get current location info for logging. :rtype: str

Added in version 4.2.

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. :rtype: tuple[str, int]

Added in version 3.0.

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).

optional_arguments = 0

Number of optional arguments after the required arguments.

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Return type:

tuple[list[Node], list[system_message]]

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

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. :rtype: None

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

transform_content(content_node)

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:

content_node (desc_content)

class sphinx_reports.CodeCoverage.CodeCoverage(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

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

Inheritance

Inheritance diagram of CodeCoverage

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).

required_arguments = 0

Number of required directive arguments.

optional_arguments = 2

Number of optional arguments after the required arguments.

option_spec: ClassVar[OptionSpec] = {'no-branch-coverage': <function flag>, '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.

_CheckOptions()[source]

Parse all directive options or use default values.

Return type:

None

run()[source]

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]

classmethod CheckConfiguration(sphinxApplication, sphinxConfiguration)

Check configuration fields and load necessary values.

Parameters:

  • sphinxApplication (Sphinx) – Sphinx application instance.

  • sphinxConfiguration (Config) – Sphinx configuration instance.

Return type:

None

classmethod ReadReports(sphinxApplication)

Read code coverage report files.

Parameters:

sphinxApplication (Sphinx) – Sphinx application instance.

Return type:

None

__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.

Added in version 1.8.

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)}

A dictionary of all configuration values used by code coverage directives.

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.

Added in version 1.8.

final_argument_whitespace = False

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

get_location()

Get current location info for logging. :rtype: str

Added in version 4.2.

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. :rtype: tuple[str, int]

Added in version 3.0.

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)

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Return type:

tuple[list[Node], list[system_message]]

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

set_source_info(node)

Set source and line number to the node. :rtype: None

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

transform_content(content_node)

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:

content_node (desc_content)

class sphinx_reports.CodeCoverage.CodeCoverageLegend(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

This directive will be replaced by a legend table representing coverage levels.

Inheritance

Inheritance diagram of CodeCoverageLegend

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).

required_arguments = 0

Number of required directive arguments.

optional_arguments = 2

Number of optional arguments after the required arguments.

option_spec: ClassVar[OptionSpec] = {'packageid': <function strip>, 'style': <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.

run()[source]

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]

classmethod CheckConfiguration(sphinxApplication, sphinxConfiguration)

Check configuration fields and load necessary values.

Parameters:

  • sphinxApplication (Sphinx) – Sphinx application instance.

  • sphinxConfiguration (Config) – Sphinx configuration instance.

Return type:

None

classmethod ReadReports(sphinxApplication)

Read code coverage report files.

Parameters:

sphinxApplication (Sphinx) – Sphinx application instance.

Return type:

None

__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.

Added in version 1.8.

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)}

A dictionary of all configuration values used by code coverage directives.

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.

Added in version 1.8.

final_argument_whitespace = False

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

get_location()

Get current location info for logging. :rtype: str

Added in version 4.2.

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. :rtype: tuple[str, int]

Added in version 3.0.

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)

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Return type:

tuple[list[Node], list[system_message]]

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

set_source_info(node)

Set source and line number to the node. :rtype: None

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

transform_content(content_node)

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:

content_node (desc_content)

class sphinx_reports.CodeCoverage.ModuleCoverage(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

This directive will be replaced by highlighted source code.

Inheritance

Inheritance diagram of ModuleCoverage

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).

required_arguments = 0

Number of required directive arguments.

optional_arguments = 2

Number of optional arguments after the required arguments.

option_spec: ClassVar[OptionSpec] = {'module': <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.

_CheckOptions()[source]

Parse all directive options or use default values.

Return type:

None

classmethod CheckConfiguration(sphinxApplication, sphinxConfiguration)

Check configuration fields and load necessary values.

Parameters:

  • sphinxApplication (Sphinx) – Sphinx application instance.

  • sphinxConfiguration (Config) – Sphinx configuration instance.

Return type:

None

classmethod ReadReports(sphinxApplication)

Read code coverage report files.

Parameters:

sphinxApplication (Sphinx) – Sphinx application instance.

Return type:

None

__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.

Added in version 1.8.

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)}

A dictionary of all configuration values used by code coverage directives.

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.

Added in version 1.8.

final_argument_whitespace = False

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

get_location()

Get current location info for logging. :rtype: str

Added in version 4.2.

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. :rtype: tuple[str, int]

Added in version 3.0.

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)

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Return type:

tuple[list[Node], list[system_message]]

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

run()[source]

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. :rtype: None

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

transform_content(content_node)

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:

content_node (desc_content)