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).


New admonition-like constructs
==============================

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

   Node for version change entries.

   Currently used for "versionadded", "versionchanged" and
   "deprecated" 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.

   New 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.
