Doctree node classes added by Sphinx

Nodes for domain-specific object descriptions

Top-level nodes

These nodes form the top-most levels of object descriptions.

class sphinx.addnodes.desc(rawsource='', *children, **attributes)

Node for a list of object signatures and a common description of them.

Contains one or more desc_signature nodes and then a single desc_content node.

This node always has two classes:

• The name of the domain it belongs to, e.g., py or cpp.

• The name of the object type in the domain, e.g., function.

class sphinx.addnodes.desc_signature(*args: Any, **kwargs: Any)

Node for a single object signature.

As default the signature is a single-line signature. Set is_multiline = True to describe a multi-line signature. In that case all child nodes must be desc_signature_line nodes.

This node always has the classes sig, sig-object, and the domain it belongs to.

class sphinx.addnodes.desc_signature_line(rawsource='', text='', *children, **attributes)

Node for a line in a multi-line object signature.

It should only be used as a child of a desc_signature with is_multiline set to True. Set add_permalink = True for the line that should get the permalink.

class sphinx.addnodes.desc_content(rawsource='', *children, **attributes)

Node for object description content.

Must be the last child node in a desc node.

class sphinx.addnodes.desc_inline(domain: str, *args: Any, **kwargs: Any)

Node for a signature fragment in inline text.

This is for example used for roles like cpp:expr.

This node always has the classes sig, sig-inline, and the name of the domain it belongs to.

Nodes for high-level structure in signatures

These nodes occur in in non-multiline desc_signature nodes and in desc_signature_line nodes.

class sphinx.addnodes.desc_name(*args: Any, **kwargs: Any)

Node for the main object name.

For example, in the declaration of a Python class MyModule.MyClass, the main name is MyClass.

This node always has the class sig-name.

class sphinx.addnodes.desc_addname(*args: Any, **kwargs: Any)

Node for additional name parts for an object.

For example, in the declaration of a Python class MyModule.MyClass, the additional name part is MyModule..

This node always has the class sig-prename.

class sphinx.addnodes.desc_type(rawsource='', text='', *children, **attributes)

Node for return types or object type names.

class sphinx.addnodes.desc_returns(rawsource='', text='', *children, **attributes)

Node for a “returns” annotation (a la -> in Python).

class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *children, **attributes)

Node for a general parameter list.

As default the parameter list is written in line with the rest of the signature. Set multi_line_parameter_list = True to describe a multi-line parameter list. In that case each parameter will then be written on its own, indented line.

class sphinx.addnodes.desc_parameter(rawsource='', text='', *children, **attributes)

Node for a single parameter.

class sphinx.addnodes.desc_optional(rawsource='', text='', *children, **attributes)

Node for marking optional parts of the parameter list.

class sphinx.addnodes.desc_annotation(rawsource='', text='', *children, **attributes)

Node for signature annotations (not Python 3-style annotations).

Nodes for signature text elements

These nodes inherit desc_sig_element and are generally translated to docutils.nodes.inline by SigElementFallbackTransform.

Extensions may create additional desc_sig_*-like nodes but in order for SigElementFallbackTransform to translate them to inline nodes automatically, they must be added to SIG_ELEMENTS via the class keyword argument _sig_element=True of desc_sig_element, e.g.:

class desc_custom_sig_node(desc_sig_element, _sig_element=True): ...

For backwards compatibility, it is still possible to add the nodes directly using SIG_ELEMENTS.add(desc_custom_sig_node).

sphinx.addnodes.SIG_ELEMENTS: set[type[desc_sig_element]]

A set of classes inheriting desc_sig_element. Each node class is expected to be handled by the builder’s translator class if the latter does not inherit from SphinxTranslator.

This set can be extended manually by third-party extensions or by subclassing desc_sig_element and using the class keyword argument _sig_element=True.

class sphinx.addnodes.desc_sig_element(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

Common parent class of nodes for inline text of a signature.

class sphinx.addnodes.desc_sig_space(rawsource: str = '', text: str = ' ', *children: Element, **attributes: Any)

Node for a space in a signature.

class sphinx.addnodes.desc_sig_name(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

Node for an identifier in a signature.

class sphinx.addnodes.desc_sig_operator(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

Node for an operator in a signature.

class sphinx.addnodes.desc_sig_punctuation(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

Node for punctuation in a signature.

class sphinx.addnodes.desc_sig_keyword(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

Node for a general keyword in a signature.

class sphinx.addnodes.desc_sig_keyword_type(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

Node for a keyword which is a built-in type in a signature.

class sphinx.addnodes.desc_sig_literal_number(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

Node for a numeric literal in a signature.

class sphinx.addnodes.desc_sig_literal_string(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

Node for a string literal in a signature.

class sphinx.addnodes.desc_sig_literal_char(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

Node for a character literal in a signature.

New admonition-like constructs

class sphinx.addnodes.versionmodified(rawsource='', text='', *children, **attributes)

Node for version change entries.

Currently used for “versionadded”, “versionchanged”, “deprecated” and “versionremoved” directives.

class sphinx.addnodes.seealso(rawsource='', *children, **attributes)

Custom “see also” admonition.

Other paragraph-level nodes

class sphinx.addnodes.compact_paragraph(rawsource='', text='', *children, **attributes)

Node for a compact paragraph (which never makes a <p> node).

New inline nodes

class sphinx.addnodes.index(rawsource='', text='', *children, **attributes)

Node for index entries.

This node is created by the index directive and has one attribute, entries. Its value is a list of 5-tuples of (entrytype, entryname, target, ignored, key).

entrytype is one of “single”, “pair”, “double”, “triple”.

key is categorization characters (usually a single character) for general index page. For the details of this, please see also: glossary and issue #2320.

class sphinx.addnodes.pending_xref(rawsource='', *children, **attributes)

Node for cross-references that cannot be resolved without complete information about all documents.

These nodes are resolved before writing output, in BuildEnvironment.resolve_references.

class sphinx.addnodes.pending_xref_condition(rawsource='', text='', *children, **attributes)

Node representing a potential way to create a cross-reference and the condition in which this way should be used.

This node is only allowed to be placed under a pending_xref node. A pending_xref node must contain either no pending_xref_condition nodes or it must only contains pending_xref_condition nodes.

The cross-reference resolver will replace a pending_xref which contains pending_xref_condition nodes by the content of exactly one of those pending_xref_condition nodes’ content. It uses the condition attribute to decide which pending_xref_condition node’s content to use. For example, let us consider how the cross-reference resolver acts on:

<pending_xref refdomain="py" reftarget="io.StringIO ...>
    <pending_xref_condition condition="resolved">
        <literal>
            StringIO
    <pending_xref_condition condition="*">
        <literal>
            io.StringIO

If the cross-reference resolver successfully resolves the cross-reference, then it rewrites the pending_xref as:

<reference>
    <literal>
        StringIO

Otherwise, if the cross-reference resolution failed, it rewrites the pending_xref as:

<reference>
    <literal>
        io.StringIO

The pending_xref_condition node should have condition attribute. Domains can be store their individual conditions into the attribute to filter contents on resolving phase. As a reserved condition name, condition="*" is used for the fallback of resolution failure. Additionally, as a recommended condition name, condition="resolved" represents a resolution success in the intersphinx module.

Added in version 4.0.

class sphinx.addnodes.literal_emphasis(rawsource='', text='', *children, **attributes)

Node that behaves like emphasis, but further text processors are not applied (e.g. smartypants for HTML output).

class sphinx.addnodes.download_reference(rawsource='', text='', *children, **attributes)

Node for download references, similar to pending_xref.

Special nodes

class sphinx.addnodes.only(rawsource='', *children, **attributes)

Node for “only” directives (conditional inclusion based on tags).

class sphinx.addnodes.highlightlang(rawsource='', *children, **attributes)

Inserted to set the highlight language and line number options for subsequent code blocks.

You should not need to generate the nodes below in extensions.

class sphinx.addnodes.glossary(rawsource='', *children, **attributes)

Node to insert a glossary.

class sphinx.addnodes.toctree(rawsource='', *children, **attributes)

Node for inserting a “TOC tree”.

class sphinx.addnodes.start_of_file(rawsource='', *children, **attributes)

Node to mark start of a new file, used in the LaTeX builder only.

class sphinx.addnodes.productionlist(rawsource='', *children, **attributes)

Node for grammar production lists.

Contains production nodes.

class sphinx.addnodes.production(rawsource='', text='', *children, **attributes)

Node for a single grammar production rule.

Previous

Parser API

Next

Logging API