Automodsumm

class plasmapy_sphinx.automodsumm.core.Automodsumm(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Autosummary

The class that defines the automodsumm directive.

Attributes Summary

`config`	Reference to the `Config` object.
`env`	Reference to the `BuildEnvironment` object.
`final_argument_whitespace`	May the final argument contain whitespace?
`has_content`	May the directive have content?
`option_spec`	Mapping of option names to validator functions.
`optional_arguments`	Number of optional arguments after the required arguments.
`required_arguments`	Number of required directive arguments.
`result`	A `docutils.statemachine.StringList` representing the lines of the directive.

Methods Summary

`add_name`(node)	Append self.options['name'] to node['names'] if it exists.
`assert_has_content`()	Throw an ERROR-level DirectiveError if the directive doesn't have contents.
`create_documenter`(app, obj, parent, full_name)	Get an autodoc.Documenter class suitable for documenting the given object.
`debug`(message)	`level=0` `directive_error()`
`directive_error`(level, message)	Return a DirectiveError suitable for being thrown as an exception.
`error`(message)	`level=3` `directive_error()`
`get_items`(names)	Try to import the given names, and return a list of `[(name, signature, summary_string, real_name), ...]`.
`get_location`()	Get current location info for logging.
`get_source_info`()	Get source and line number.
`get_table`(items)	Generate a proper list of table nodes for autosummary:: directive.
`import_by_name`(name, prefixes)	See `sphinx.ext.autosummary.import_by_name()`
`info`(message)	`level=1` `directive_error()`
`option_processor`()	Instance of `Automodsumm` so further processing (beyond `option_spec`) of directive options can be performed.
`parse_content_to_nodes`([allow_section_headings])	Parse the directive's content into nodes.
`parse_inline`(text, *[, lineno])	Parse text as inline elements.
`parse_text_to_nodes`([text, offset, ...])	Parse text into nodes.
`run`()	This method is called whenever the `automodsumm` directive is found in a document.
`set_source_info`(node)	Set source and line number to the node.
`severe`(message)	`level=4` `directive_error()`
`warning`(message)	`level=2` `directive_error()`

Attributes Documentation

config: Reference to the Config object.

env: Reference to the BuildEnvironment object.

final_argument_whitespace = False: May the final argument contain whitespace?

has_content = False: May the directive have content?

option_spec: ClassVar[OptionSpec] = {'caption': <function unchanged_required>, 'exclude-groups': <function option_str_list>, 'groups': <function option_str_list>, 'nosignatures': <function flag>, 'recursive': <function flag>, 'skip': <function option_str_list>, 'template': <function unchanged>, 'toctree': <function unchanged>}: Mapping of option names to validator functions.

optional_arguments = 0: Number of optional arguments after the required arguments.

required_arguments = 1: Number of required directive arguments.

result: A docutils.statemachine.StringList representing the lines of the directive.

Methods Documentation

add_name(node)

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

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

assert_has_content(): Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

create_documenter(app: Sphinx, obj: Any, parent: Any, full_name: str) → Documenter

Get an autodoc.Documenter class suitable for documenting the given object.

Wraps get_documenter and is meant as a hook for extensions.

debug(message): level=0 directive_error()

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.

error(message): level=3 directive_error()

get_items(names): Try to import the given names, and return a list of [(name, signature, summary_string, real_name), ...].

get_location() → str: Get current location info for logging.

Added in version 4.2.

get_source_info() → tuple[str, int]: Get source and line number.

Added in version 3.0.

get_table(items: list[tuple[str, str, str, str]]) → list[Node]

Generate a proper list of table nodes for autosummary:: directive.

items is a list produced by get_items().

import_by_name(name: str, prefixes: List[str]) → Tuple[str, Any, Any, str]: See sphinx.ext.autosummary.import_by_name()

info(message): level=1 directive_error()

option_processor(): Instance of Automodsumm so further processing (beyond option_spec) of directive options can be performed.

parse_content_to_nodes(allow_section_headings: bool = False) → list[Node]

Parse the directive’s content into nodes.

Parameters:: allow_section_headings – 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.

Added in version 7.4.

parse_inline(text: str, *, lineno: int = -1) → tuple[list[Node], list[system_message]]

Parse text as inline elements.

Parameters:

text – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).
lineno – The line number where the interpreted text begins.

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: str = '', /, *, offset: int = -1, allow_section_headings: bool = False) → list[Node]

Parse text into nodes.

Parameters:

text – Text, in string form. StringList is also accepted.
allow_section_headings – 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 – The offset of the content.

Added in version 7.4.

run(): This method is called whenever the automodsumm directive is found in a document. It is used to do any further manipulation of the directive, its options, and its content to get the desired rendered outcome.

set_source_info(node: Node) → None: Set source and line number to the node.

Added in version 2.1.

severe(message): level=4 directive_error()

warning(message): level=2 directive_error()