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 singledesc_content
node.This node always has two classes:
The name of the domain it belongs to, e.g.,
py
orcpp
.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 bedesc_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
withis_multiline
set toTrue
. Setadd_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 isMyClass
.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 isMyModule.
.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 <p> 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 incondition
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.