Sphinx 添加的 Doctree 节点类¶

用于特定领域对象描述的节点¶

顶级节点¶

这些节点构成了对象描述的最高级别。

class sphinx.addnodes.desc(rawsource: str = '', *children, **attributes: Any)[源]¶

用于对象签名列表及其共同描述的节点。

包含一个或多个 desc_signature 节点，然后是一个 desc_content 节点。

此节点始终具有两个类

它所属的领域名称，例如 py 或 cpp。
领域中对象类型的名称，例如 function。

class sphinx.addnodes.desc_signature(*args: Any, **kwargs: Any)[源]¶

用于单个对象签名的节点。

默认情况下，签名是单行签名。设置 is_multiline = True 可描述多行签名。在这种情况下，所有子节点都必须是 desc_signature_line 节点。

此节点始终具有类 sig、sig-object 及其所属领域。

class sphinx.addnodes.desc_signature_line(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶

用于多行对象签名中的一行的节点。

它应该只用作 desc_signature 的子节点，并且 is_multiline 设置为 True。对于应该获得永久链接的行，设置 add_permalink = True。

class sphinx.addnodes.desc_content(rawsource: str = '', *children, **attributes: Any)[源]¶

用于对象描述内容的节点。

必须是 desc 节点中的最后一个子节点。

class sphinx.addnodes.desc_inline(domain: str, *args: Any, **kwargs: Any)[源]¶

用于内联文本中签名片段的节点。

例如，这用于像 cpp:expr 这样的角色。

此节点始终具有类 sig、sig-inline 及其所属领域的名称。

用于签名中高级结构的节点¶

这些节点出现在非多行 desc_signature 节点和 desc_signature_line 节点中。

class sphinx.addnodes.desc_name(*args: Any, **kwargs: Any)[源]¶

用于主要对象名称的节点。

例如，在 Python 类 MyModule.MyClass 的声明中，主要名称是 MyClass。

此节点始终具有类 sig-name。

class sphinx.addnodes.desc_addname(*args: Any, **kwargs: Any)[源]¶

用于对象的附加名称部分的节点。

例如，在 Python 类 MyModule.MyClass 的声明中，附加名称部分是 MyModule.。

此节点始终具有类 sig-prename。

class sphinx.addnodes.desc_type(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶: 用于返回类型或对象类型名称的节点。

class sphinx.addnodes.desc_returns(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶: 用于“返回”注解（Python 中的 ->）的节点。

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

用于通用参数列表的节点。

默认情况下，参数列表与签名的其余部分在一行中书写。设置 multi_line_parameter_list = True 可描述多行参数列表。在这种情况下，每个参数将单独缩进一行。如果 multi_line_trailing_comma 为 True，则最后一行将添加一个尾随逗号。

class sphinx.addnodes.desc_parameter(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶: 用于单个参数的节点。

class sphinx.addnodes.desc_optional(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶: 用于标记参数列表可选部分的节点。

class sphinx.addnodes.desc_annotation(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶: 用于签名注解的节点（不是 Python 3 风格的注解）。

用于签名文本元素的节点¶

这些节点继承自 desc_sig_element，通常由 SigElementFallbackTransform 转换为 docutils.nodes.inline。

扩展可以创建额外的类似 desc_sig_* 的节点，但为了使 SigElementFallbackTransform 自动将它们转换为内联节点，它们必须通过 desc_sig_element 的类关键字参数 _sig_element=True 添加到 SIG_ELEMENTS 中，例如

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

为了向后兼容，仍然可以直接使用 SIG_ELEMENTS.add(desc_custom_sig_node) 添加节点。

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

一个继承自 desc_sig_element 的类集合。如果构建器的翻译类不继承自 SphinxTranslator，则预期每个节点类都将由其处理。

此集合可以通过第三方扩展手动扩展，或者通过子类化 desc_sig_element 并使用类关键字参数 _sig_element=True 来扩展。

class sphinx.addnodes.desc_sig_element(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)[源]¶: 签名内联文本节点的公共父类。

class sphinx.addnodes.desc_sig_space(rawsource: str = '', text: str = ' ', *children: Element, **attributes: Any)[源]¶: 用于签名中空格的节点。

class sphinx.addnodes.desc_sig_name(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)[源]¶: 用于签名中标识符的节点。

class sphinx.addnodes.desc_sig_operator(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)[源]¶: 用于签名中运算符的节点。

class sphinx.addnodes.desc_sig_punctuation(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)[源]¶: 用于签名中标点符号的节点。

class sphinx.addnodes.desc_sig_keyword(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)[源]¶: 用于签名中通用关键字的节点。

class sphinx.addnodes.desc_sig_keyword_type(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)[源]¶: 用于签名中作为内置类型的关键字的节点。

class sphinx.addnodes.desc_sig_literal_number(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)[源]¶: 用于签名中数字字面量的节点。

class sphinx.addnodes.desc_sig_literal_string(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)[源]¶: 用于签名中字符串字面量的节点。

class sphinx.addnodes.desc_sig_literal_char(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)[源]¶: 用于签名中字符字面量的节点。

新增的类似警示的结构¶

class sphinx.addnodes.versionmodified(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶

用于版本更改条目的节点。

目前用于“version-added”、“version-changed”、“version-deprecated”和“version-removed”指令及其别名。

class sphinx.addnodes.seealso(rawsource: str = '', *children, **attributes: Any)[源]¶: 自定义的“参见”警示。

其他段落级节点¶

class sphinx.addnodes.compact_paragraph(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶: 用于紧凑段落的节点（从不生成 <p> 节点）。

新增的内联节点¶

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

用于索引条目的节点。

此节点由 index 指令创建，具有一个属性 entries。其值是 5 元组 (entrytype, entryname, target, ignored, key) 的列表。

entrytype 是“single”、“pair”、“double”、“triple”之一。

key 是用于通用索引页面的分类字符（通常是单个字符）。有关详细信息，请参阅：glossary 和 https://github.com/sphinx-doc/sphinx/pull/2320。

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

用于在没有所有文档的完整信息的情况下无法解析的交叉引用的节点。

这些节点在输出写入之前在 BuildEnvironment.resolve_references 中解析。

class sphinx.addnodes.pending_xref_condition(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶

表示创建交叉引用的潜在方式以及应使用此方式的条件的节点。

此节点只允许放置在 pending_xref 节点下。一个 pending_xref 节点必须不包含 pending_xref_condition 节点，或者只包含 pending_xref_condition 节点。

交叉引用解析器将用这些 pending_xref_condition 节点中一个节点的完整内容替换包含 pending_xref_condition 节点的 pending_xref。它使用 condition 属性来决定使用哪个 pending_xref_condition 节点的内容。例如，让我们考虑交叉引用解析器如何处理

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

如果交叉引用解析器成功解析了交叉引用，则它将 pending_xref 重写为

<reference>
    <literal>
        StringIO

否则，如果交叉引用解析失败，它将 pending_xref 重写为

<reference>
    <literal>
        io.StringIO

pending_xref_condition 节点应具有 condition 属性。领域可以在属性中存储其单独的条件，以在解析阶段过滤内容。作为一个保留的条件名称，condition="*" 用于解析失败的回退。此外，作为一个推荐的条件名称，condition="resolved" 表示 intersphinx 模块中的解析成功。

4.0 版本新增。

class sphinx.addnodes.literal_emphasis(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶: 表现得像 emphasis 的节点，但不会应用进一步的文本处理器（例如 HTML 输出的 smartypants）。

class sphinx.addnodes.download_reference(rawsource: str = '', text: str = '', *children, **attributes: Any)[源]¶: 用于下载引用的节点，类似于 pending_xref。

特殊节点¶

class sphinx.addnodes.only(rawsource: str = '', *children, **attributes: Any)[源]¶: 用于“only”指令的节点（基于标签的条件包含）。

class sphinx.addnodes.highlightlang(rawsource: str = '', *children, **attributes: Any)[源]¶: 插入以设置后续代码块的突出显示语言和行号选项。

您无需在扩展中生成以下节点。

class sphinx.addnodes.glossary(rawsource: str = '', *children, **attributes: Any)[源]¶: 插入词汇表的节点。

class sphinx.addnodes.toctree(rawsource: str = '', *children, **attributes: Any)[源]¶: 用于插入“TOC 树”的节点。

class sphinx.addnodes.start_of_file(rawsource: str = '', *children, **attributes: Any)[源]¶: 用于标记新文件开始的节点，仅在 LaTeX 构建器中使用。

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

用于语法生成列表的节点。

包含 production 节点。

class sphinx.addnodes.production(rawsource: str = '', text: str = '', *children, **attributes: Any)[source]¶: 单个语法生成规则的节点。