Sphinx

# 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: str = '', *children, **attributes: Any)

  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: str = '', text: str = '', *children, **attributes: Any)

  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: str = '', *children, **attributes: Any)

  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: str = '', text: str = '', *children, **attributes: Any)

  Node for return types or object type names.

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

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

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

  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. A trailing comma will be added on the last line if `multi_line_trailing_comma` is True.

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

  Node for a single parameter.

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

  Node for marking optional parts of the parameter list.

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

  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: str = '', text: str = '', *children, **attributes: Any)

  Node for version change entries.

  Currently used for “version-added”, “version-changed”, “version-deprecated” and “version-removed” directives, along with their aliases.

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

  Custom “see also” admonition.

## Other paragraph-level nodes

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

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

## New inline nodes

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

  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 https://github.com/sphinx-doc/sphinx/pull/2320.

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

  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: str = '', text: str = '', *children, **attributes: Any)

  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: str = '', text: str = '', *children, **attributes: Any)

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

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

  Node for download references, similar to pending_xref.

## Special nodes

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

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

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

  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: str = '', *children, **attributes: Any)

  Node to insert a glossary.

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

  Node for inserting a “TOC tree”.

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

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

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

  Node for grammar production lists.

  Contains `production` nodes.

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

  Node for a single grammar production rule.