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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]: Node for return types or object type names.

class sphinx.addnodes.desc_returns(rawsource=', text=', *children, **attributes)[source]: Node for a “returns” annotation (a la -> in Python).

class sphinx.addnodes.desc_parameterlist(rawsource=', text=', *children, **attributes)[source]: Node for a general parameter list.

class sphinx.addnodes.desc_parameter(rawsource=', text=', *children, **attributes)[source]: Node for a single parameter.

class sphinx.addnodes.desc_optional(rawsource=', text=', *children, **attributes)[source]: Node for marking optional parts of the parameter list.

class sphinx.addnodes.desc_annotation(rawsource=', text=', *children, **attributes)[source]: Node for signature annotations (not Python 3-style annotations).

New admonition-like constructs

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

Node for version change entries.

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

class sphinx.addnodes.seealso(rawsource='', *children, **attributes)[source]: Custom “see also” admonition.

Other paragraph-level nodes

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

Node for a compact paragraph (which never makes a

node).

New inline nodes

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

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)[source]

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)[source]

Node for cross-references that are used to choose appropriate content of the reference by conditions on the resolving phase.

When the pending_xref node contains one or more pending_xref_condition nodes, the cross-reference resolver should choose the content of the reference using defined conditions in condition attribute of each pending_xref_condition nodes:

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

After the processing of cross-reference resolver, one of the content node under pending_xref_condition node is chosen by its condition and to be removed all of pending_xref_condition nodes:

# When resolved the cross-reference successfully
<reference>
    <literal>
        StringIO

# When resolution is failed
<reference>
    <literal>
        io.StringIO

Note

This node is only allowed to be placed under pending_xref node. It is not allows to place it under other nodes. In addition, pending_xref node must contain only pending_xref_condition nodes if it contains one or more pending_xref_condition nodes.

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" is used for the representation of resolstion success in the intersphinx module.

New in version 4.0.

class sphinx.addnodes.literal_emphasis(rawsource=', text=', *children, **attributes)[source]: 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)[source]: Node for download references, similar to pending_xref.

Special nodes

class sphinx.addnodes.only(rawsource='', *children, **attributes)[source]: Node for “only” directives (conditional inclusion based on tags).

class sphinx.addnodes.meta(rawsource='', *children, **attributes)[source]: Node for meta directive – same as docutils’ standard meta node, but pickleable.

class sphinx.addnodes.highlightlang(rawsource='', *children, **attributes)[source]: 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)[source]: Node to insert a glossary.

class sphinx.addnodes.toctree(rawsource='', *children, **attributes)[source]: Node for inserting a “TOC tree”.

class sphinx.addnodes.start_of_file(rawsource='', *children, **attributes)[source]: Node to mark start of a new file, used in the LaTeX builder only.

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

Node for grammar production lists.

Contains production nodes.

class sphinx.addnodes.production(rawsource=', text=', *children, **attributes)[source]: Node for a single grammar production rule.