vhdl_domain module

Implements the Sphinx VHDL Domain and roles

Module functions summary

vhdl_code_role

Define the vhdl role, which inserts the specified raw text as a literal block of text color-highlighted with Pygments for the VHDL syntax.

Module classes summary

VHDLDirective

A generic directive that is to be used as a base class for directives documenting VHDL elements such as Entity, Architecture etc.

VHDLDomain

Class defining the VHDL Domain.

VHDLEntityDirective

Insert the entity brief description, generics/ports table and long description

VHDLIncludeDirective

Includes a specified range of VHDL comment lines in this document as restructuredText or MarkDown

VHDLParseDirective

Loads and parse the specified VHDL file.

VHDLXRefRole

VHDL cross-reference role

Module functions

vhdl_code_role(role, rawtext, text, lineno, inliner, options={}, content=[])

Define the vhdl role, which inserts the specified raw text as a literal block of text color-highlighted with Pygments for the VHDL syntax.

Parameters:

  • role – unused

  • rawtext (str) – raw text of the role

  • text – text between the backticks

  • lineno

  • inliner

  • options (dict)

  • content (list)

Returns:

a (node_list, error_message_list) tuple

Return type:

tuple

Module classes

class VHDLDirective(name, arguments, options, *args)

Bases: ObjectDescription

A generic directive that is to be used as a base class for directives documenting VHDL elements such as Entity, Architecture etc. This class offers:

  • x-ref directive registered with Sphinx.add_object_type().

The following attributes are commonly used:

  • data (Object): The VHDLDomain associated data. Convenient shortcut for self.env.domaindata['vhdl']. Initialized at instatiation. Must be picklable, as Sphinx saves it to disk for each processed file.

  • vhdl_parser (VHDLParser): Represent the VHDLDomain’s VHDL parser object, which holds the results of all parsed files. Attribute initialized at instantiation.

  • name (str): full name of the directive (e.g. vhdl:autoentity) (initialized by run())

  • objtype (str): type of object being handled by the directive (entity, architecture etc), extracted from name (initialized by run())

  • domain (str): name of the domain fir this directive. Extracted from name. (initialized by run())

__init__(name, arguments, options, *args)

Initializes the VHDL directive by creating the .data and .vhdl_parser attributes that point to the domain data nd parser respectively.

Parameters:

  • name (str) – name of the directive

  • argument (list) – list of arguments following the directive

  • options (dict) – keyword options and values provided to the directive

  • args (list) – other arguments, passed to the class parent

add_contents()

Appends content nodes to the directive output. To be overriden by the object-specific directive.

This is VHDLDirective-specific method.

Returns:

list of docutils nodes to be appended to the output of run().

Return type:

list

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)
Parameters:

  • name – value that identifies the object. This is the value returned by handle_signature().

  • sig (list) – signatures (list of strings) obtained from get_signature().

  • signode (list) – signature node that we will be referring to

Attributes used in this method:

  • self.objtype (str): the type of object (entity, architecture etc.) to be used to crate the entry in the cross reference table.

  • self.link_to_top (boolean): if true, the ling will point to the top of the page, otherwise it will point to this entry

  • self.domain (str): the current domain name (e.g. VHDL)

  • self.data[‘objects’]: The cross_reference dictionary for this domain, indexed by (type,name), pointing to (document_name, target_name)

after_content() → None

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

assert_has_content()

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

before_content() → None

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

property config: Config

Reference to the Config object.

Added in version 1.8.

debug(message)
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.

doc_field_types: list[Field] = []
domain: str | None = 'vhdl'
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

error(message)
final_argument_whitespace = True

May the final argument contain whitespace?

get_field_type_map() → dict[str, tuple[Field, bool]]
get_location() → str

Get current location info for logging.

Added in version 4.2.

get_signatures() → list[str]

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

get_source_info() → tuple[str, int]

Get source and line number.

Added in version 3.0.

handle_signature(sig, signode)

Parse the signature sig into individual nodes and append them to signode.

Parameters:

  • sig (str) – signature of the directive

  • signode (list) – list of nodes to which the signature should be added

Returns:

value that identifies the object, which will be passed to add_target_and_index().

Return type:

str

has_content = True

May the directive have content?

indexnode: addnodes.index
indextemplate = '%s; entity'
info(message)
objtype: str
option_spec: ClassVar[OptionSpec] = {'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

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.

required_arguments = 1

Number of required directive arguments.

run()

Process the directive.

We update the name of the object by removing the auto prefix, run the parent run() method, and then add additional contents provided by add_contents().

Attributes used in this method:

  • name (str): full name of the directive, with domain prefix (e.g. vhdl:autoentity)

set_source_info(node: Node) → None

Set source and line number to the node.

Added in version 2.1.

severe(message)
transform_content(content_node: desc_content) → None

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.

warning(message)
class VHDLDomain(env)

Bases: Domain

Class defining the VHDL Domain. Instance of this class holds the domain state, including the VHDLParser instance.

__init__(env)

Create the VHDL domain instance, including a VHDLParser instance.

Parameters:

env (sphinx.BuildEnvironment) – instance of the build environment object that will hold the list of objects created by this domain.

add_object_type(name: str, objtype: ObjType) → None

Add an object type.

check_consistency() → None

Do consistency checks (experimental).

clear_doc(docname, verbose=0)

Remove traces of a document in the domain-specific inventories.

dangling_warnings: dict[str, str] = {}

role name -> a warning message if reference is missing

data: dict[str, Any]

data value

data_version = 0

data version, bump this when the format of self.data changes

directive(name: str) → Callable | None

Return a directive adapter class that always gives the registered directive its full name (‘domain:name’) as self.name.

directives: dict[str, type[Directive]] = {'autoentity': <class 'vhdl_sphinx_domain.vhdl_domain.VHDLEntityDirective'>, 'include-docs': <class 'vhdl_sphinx_domain.vhdl_domain.VHDLIncludeDirective'>, 'parse': <class 'vhdl_sphinx_domain.vhdl_domain.VHDLParseDirective'>}

directive name -> directive class

enumerable_nodes: dict[type[Node], tuple[str, TitleGetter | None]] = {}

node_class -> (enum_node_type, title_getter)

get_enumerable_node_type(node: Node) → str | None

Get type of enumerable nodes (experimental).

get_full_qualified_name(node: Element) → str | None

Return full qualified name for given node.

get_objects()

Return an iterable of “object descriptions”.

Object descriptions are tuples with six items:

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.

indices: list[type[Index]] = []

a list of Index subclasses

initial_data: dict = {'objects': {}, 'parser': None}

data value for a fresh environment

label = 'VHDL'

longer, more descriptive (used in messages)

Type:

domain label

merge_domaindata(docnames: Set[str], otherdata: dict[str, Any]) → None

Merge in data regarding docnames from a different domaindata inventory (coming from a subprocess in parallel builds).

name = 'vhdl'

should be short, but unique

Type:

domain name

object_types: dict[str, ObjType] = {'entity': <sphinx.domains.ObjType object>, 'target': <sphinx.domains.ObjType object>}

type (usually directive) name -> ObjType instance

process_doc(env: BuildEnvironment, docname: str, document: nodes.document) → None

Process a document after it is read by the environment.

process_field_xref(pnode: pending_xref) → None

Process a pending xref created in a doc field. For example, attach information about the current scope.

resolve_any_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: pending_xref, contnode: Element) → list[tuple[str, Element]]

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.

Added in version 1.3.

resolve_xref(env, fromdocname, builder, typ, target, node, contnode)
role(name: str) → RoleFunction | None

Return a role adapter function that always gives the registered role its full name (‘domain:name’) as the first argument.

roles: dict[str, RoleFunction | XRefRole] = {'entity': <vhdl_sphinx_domain.vhdl_domain.VHDLXRefRole object>, 'vhdl': <function vhdl_code_role>}

role name -> role callable

setup() → None

Set up domain object.

class VHDLEntityDirective(name, arguments, options, *args)

Bases: VHDLDirective

Insert the entity brief description, generics/ports table and long description

Directive arguments: vhdl_entity_name

Directive options: None

__init__(name, arguments, options, *args)

Initializes the VHDL directive by creating the .data and .vhdl_parser attributes that point to the domain data nd parser respectively.

Parameters:

  • name (str) – name of the directive

  • argument (list) – list of arguments following the directive

  • options (dict) – keyword options and values provided to the directive

  • args (list) – other arguments, passed to the class parent

add_contents()

Adds the entity’s short description, generics and port interface table, and long description nodes to the directive’s output

Returns:

list of nodes to add

Return type:

list

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)
Parameters:

  • name – value that identifies the object. This is the value returned by handle_signature().

  • sig (list) – signatures (list of strings) obtained from get_signature().

  • signode (list) – signature node that we will be referring to

Attributes used in this method:

  • self.objtype (str): the type of object (entity, architecture etc.) to be used to crate the entry in the cross reference table.

  • self.link_to_top (boolean): if true, the ling will point to the top of the page, otherwise it will point to this entry

  • self.domain (str): the current domain name (e.g. VHDL)

  • self.data[‘objects’]: The cross_reference dictionary for this domain, indexed by (type,name), pointing to (document_name, target_name)

after_content() → None

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

assert_has_content()

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

before_content() → None

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

property config: Config

Reference to the Config object.

Added in version 1.8.

debug(message)
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.

doc_field_types: list[Field] = []
domain: str | None = 'vhdl'
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

error(message)
final_argument_whitespace = True

May the final argument contain whitespace?

get_field_type_map() → dict[str, tuple[Field, bool]]
get_location() → str

Get current location info for logging.

Added in version 4.2.

get_signatures() → list[str]

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

get_source_info() → tuple[str, int]

Get source and line number.

Added in version 3.0.

handle_signature(sig, signode)

Parse the signature sig into individual nodes and append them to signode.

Parameters:

  • sig (str) – signature of the directive

  • signode (list) – list of nodes to which the signature should be added

Returns:

value that identifies the object, which will be passed to add_target_and_index().

Return type:

str

has_content = True

May the directive have content?

indexnode: addnodes.index
indextemplate = '%s; entity'
info(message)
objtype: str
option_spec: ClassVar[OptionSpec] = {'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

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.

required_arguments = 1

Number of required directive arguments.

run()

Process the directive.

We update the name of the object by removing the auto prefix, run the parent run() method, and then add additional contents provided by add_contents().

Attributes used in this method:

  • name (str): full name of the directive, with domain prefix (e.g. vhdl:autoentity)

set_source_info(node: Node) → None

Set source and line number to the node.

Added in version 2.1.

severe(message)
transform_content(content_node: desc_content) → None

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.

warning(message)
class VHDLIncludeDirective(name, arguments, options, *args)

Bases: VHDLDirective

Includes a specified range of VHDL comment lines in this document as restructuredText or MarkDown

Directive argument: The entity name in which file the comment lines will searched and extracted from

Directive options:

  • start_before (str): start including text from the comment line containing the specified string

  • start_after (str): start including text from the comment line following the line containing the specified string

  • start_before (str): stop including text before the comment line contining the specified string

  • start_after (str): stop including text on the comment line contining the specified string

Example:

..vhdl:include:: GPIO
    :start-after: Memory Map
__init__(name, arguments, options, *args)

Create and initialize a directive object instance.

Parameters:

  • name (str) – name of the directive

  • arguments (str) – arguments passed after the directive (i.e. the signature, <directive_name>: <arguments>)

  • options (dict) – options passed to the directive (i.e. :<option_name>: <option_value>)

  • *args – All other options passed to the parent’s __init__

add_contents()

Appends content nodes to the directive output. To be overriden by the object-specific directive.

This is VHDLDirective-specific method.

Returns:

list of docutils nodes to be appended to the output of run().

Return type:

list

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)
Parameters:

  • name – value that identifies the object. This is the value returned by handle_signature().

  • sig (list) – signatures (list of strings) obtained from get_signature().

  • signode (list) – signature node that we will be referring to

Attributes used in this method:

  • self.objtype (str): the type of object (entity, architecture etc.) to be used to crate the entry in the cross reference table.

  • self.link_to_top (boolean): if true, the ling will point to the top of the page, otherwise it will point to this entry

  • self.domain (str): the current domain name (e.g. VHDL)

  • self.data[‘objects’]: The cross_reference dictionary for this domain, indexed by (type,name), pointing to (document_name, target_name)

after_content() → None

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

assert_has_content()

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

before_content() → None

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

property config: Config

Reference to the Config object.

Added in version 1.8.

debug(message)
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.

doc_field_types: list[Field] = []
domain: str | None = 'vhdl'
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

error(message)
final_argument_whitespace = True

May the final argument contain whitespace?

get_field_type_map() → dict[str, tuple[Field, bool]]
get_location() → str

Get current location info for logging.

Added in version 4.2.

get_signatures() → list[str]

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

get_source_info() → tuple[str, int]

Get source and line number.

Added in version 3.0.

handle_signature(sig, signode)

Parse the signature sig into individual nodes and append them to signode.

Parameters:

  • sig (str) – signature of the directive

  • signode (list) – list of nodes to which the signature should be added

Returns:

value that identifies the object, which will be passed to add_target_and_index().

Return type:

str

has_content = False

May the directive have content?

indexnode: addnodes.index
indextemplate = '%s; entity'
info(message)
objtype: str
option_spec: ClassVar[OptionSpec] = {'end-after': <function VHDLIncludeDirective.<lambda>>, 'end-before': <function VHDLIncludeDirective.<lambda>>, 'start-after': <function VHDLIncludeDirective.<lambda>>, 'start-before': <function VHDLIncludeDirective.<lambda>>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

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.

required_arguments = 1

Number of required directive arguments.

run()

Process the directive.

We update the name of the object by removing the auto prefix, run the parent run() method, and then add additional contents provided by add_contents().

Attributes used in this method:

  • name (str): full name of the directive, with domain prefix (e.g. vhdl:autoentity)

set_source_info(node: Node) → None

Set source and line number to the node.

Added in version 2.1.

severe(message)
transform_content(content_node: desc_content) → None

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.

warning(message)
class VHDLParseDirective(name, arguments, options, *args)

Bases: VHDLDirective

Loads and parse the specified VHDL file.

The parse results are stored in the vhdl_parser object for reference by other directives.

Directive arguments: vhdl_file_name

Directive options: None

__init__(name, arguments, options, *args)

Initialize the directive by extracting the directive argument.

add_contents()

Appends content nodes to the directive output. To be overriden by the object-specific directive.

This is VHDLDirective-specific method.

Returns:

list of docutils nodes to be appended to the output of run().

Return type:

list

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)
Parameters:

  • name – value that identifies the object. This is the value returned by handle_signature().

  • sig (list) – signatures (list of strings) obtained from get_signature().

  • signode (list) – signature node that we will be referring to

Attributes used in this method:

  • self.objtype (str): the type of object (entity, architecture etc.) to be used to crate the entry in the cross reference table.

  • self.link_to_top (boolean): if true, the ling will point to the top of the page, otherwise it will point to this entry

  • self.domain (str): the current domain name (e.g. VHDL)

  • self.data[‘objects’]: The cross_reference dictionary for this domain, indexed by (type,name), pointing to (document_name, target_name)

after_content() → None

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

assert_has_content()

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

before_content() → None

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

property config: Config

Reference to the Config object.

Added in version 1.8.

debug(message)
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.

doc_field_types: list[Field] = []
domain: str | None = 'vhdl'
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

error(message)
final_argument_whitespace = True

May the final argument contain whitespace?

get_field_type_map() → dict[str, tuple[Field, bool]]
get_location() → str

Get current location info for logging.

Added in version 4.2.

get_signatures() → list[str]

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

get_source_info() → tuple[str, int]

Get source and line number.

Added in version 3.0.

handle_signature(sig, signode)

Parse the signature sig into individual nodes and append them to signode.

Parameters:

  • sig (str) – signature of the directive

  • signode (list) – list of nodes to which the signature should be added

Returns:

value that identifies the object, which will be passed to add_target_and_index().

Return type:

str

has_content = False

May the directive have content?

indexnode: addnodes.index
indextemplate = '%s; entity'
info(message)
objtype: str
option_spec: ClassVar[OptionSpec] = {'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

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.

required_arguments = 1

Number of required directive arguments.

run()

Executes the directive by parsing the specified filename and storing the result in the domain’s parser object for future references.

Returns:

list of nodes to add to the document. In this case, this is an empty list.

Return type:

list

set_source_info(node: Node) → None

Set source and line number to the node.

Added in version 2.1.

severe(message)
transform_content(content_node: desc_content) → None

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.

warning(message)
class VHDLXRefRole(fix_parens: bool = False, lowercase: bool = False, nodeclass: type[Element] | None = None, innernodeclass: type[TextElement] | None = None, warn_dangling: bool = False)

Bases: XRefRole

VHDL cross-reference role

__call__(name: str, rawtext: str, text: str, lineno: int, inliner: Inliner, options: dict | None = None, content: Sequence[str] = ()) → tuple[list[Node], list[system_message]]

Call self as a function.

__init__(fix_parens: bool = False, lowercase: bool = False, nodeclass: type[Element] | None = None, innernodeclass: type[TextElement] | None = None, warn_dangling: bool = False) → None
property config: Config

Reference to the Config object.

Added in version 2.0.

content: Sequence[str]

A list of strings, the directive content for customisation (from the “role” directive).

create_non_xref_node() → tuple[list[Node], list[system_message]]
create_xref_node() → tuple[list[Node], list[system_message]]
disabled: bool

A boolean indicates the reference is disabled.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 2.0.

explicit_title_re = re.compile('^(.+?)\\s*(?<!\\x00)<(.*?)>$', re.DOTALL)
get_location() → str

Get current location info for logging.

Added in version 4.2.

get_source_info(lineno: int | None = None) → tuple[str, int]
has_explicit_title: bool

A boolean indicates the role has explicit title or not.

inliner: Inliner

The docutils.parsers.rst.states.Inliner object.

innernodeclass

alias of literal

lineno: int

The line number where the interpreted text begins.

name: str

The role name actually used in the document.

nodeclass

alias of pending_xref

options: dict[str, Any]

A dictionary of directive options for customisation (from the “role” directive).

Called after parsing title and target text, and creating the reference node (given in refnode). This method can alter the reference node and must return a new (or the same) (title, target) tuple.

rawtext: str

A string containing the entire interpreted text input.

result_nodes(document: nodes.document, env: BuildEnvironment, node: Element, is_ref: bool) → tuple[list[Node], list[system_message]]

Called before returning the finished nodes. node is the reference node if one was created (is_ref is then true), else the content node. This method can add other nodes and must return a (nodes, messages) tuple (the usual return value of a role function).

run() → tuple[list[Node], list[system_message]]
set_source_info(node: Node, lineno: int | None = None) → None
target: str

The link target for the interpreted text.

text: str

The interpreted text content.

title: str

The link title for the interpreted text.

update_title_and_target(title: str, target: str) → tuple[str, str]