sphinx_reports.Sphinx
Helper functions and derived classes from Sphinx.
Functions
strip(): Undocumented.
Classes
BaseDirective: Directive to describe a class, function or similar object. Not used
Functions
Classes
- class sphinx_reports.Sphinx.BaseDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
Inheritance
-
has_content:
bool= False A boolean;
Trueif 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 = 0
Number of optional arguments after the required arguments.
- final_argument_whitespace = False
A boolean, indicating if the final argument may contain whitespace.
- option_spec: ClassVar[OptionSpec] = {}
Mapping of option names to validator functions.
A dictionary, mapping known option names to conversion functions such as
intorfloat(default: {}, no options). Several conversion functions are defined in thedirectives/__init__.pymodule.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 raiseValueErrorandTypeErrorexceptions.
- __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.
- _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_nameis set on the object node, later used inenvironment.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 assig_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_partsattribute within thehandle_signature()method.- Return type:
- 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.
- after_content()
Called after parsing content. Used to reset information about the current directive context on the build environment.
- Return type:
- 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:
- property config: Config
Reference to the
Configobject.
- 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
BuildEnvironmentobject.
- get_signatures()
Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.
- 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.
- 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:
- Parameters:
node (Node)
-
has_content: