Sphinx 添加的文档树节点类

特定领域对象描述的节点

顶级节点

这些节点构成对象描述的最顶层。

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

对象签名列表及其通用描述的节点。

包含一个或多个 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='', text='', *children, **attributes)

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

它应该仅用作 is_multiline 设置为 True 的 desc_signature 的子节点。对于应获取永久链接的行，请设置 add_permalink = True。

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

对象描述内容的节点。

必须是 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='', text='', *children, **attributes)

用于返回类型或对象类型名称的节点。

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

用于“returns”注释（如 Python 中的 ->）的节点。

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

用于一般参数列表的节点。

默认情况下，参数列表与签名其余部分在同一行书写。设置 multi_line_parameter_list = True 来描述多行参数列表。在这种情况下，每个参数将分别书写在自己的缩进行上。

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

用于单个参数的节点。

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

用于标记参数列表可选部分的节点。

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

用于签名注释（非 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='', text='', *children, **attributes)

版本变更条目节点。

当前用于“versionadded”、“versionchanged”、“deprecated”和“versionremoved”指令。

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

自定义“参见”提示。

其他段落级节点

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

紧凑段落（从不生成<p>节点）的节点。

新的内联节点

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

索引条目的节点。

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

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

key 是通用索引页面的分类字符（通常为单个字符）。有关此内容的详细信息，另请参见：glossary 和 issue #2320。

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

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

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

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

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

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

交叉引用解析器将替换包含pending_xref_condition节点的pending_xref，替换为这些pending_xref_condition节点内容中的一个。它使用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

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

<reference>
    <literal>
        StringIO

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

<reference>
    <literal>
        io.StringIO

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

版本 4.0 中新增。

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

行为类似于emphasis的节点，但不会应用进一步的文本处理器（例如，HTML 输出的 smartypants）。

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

下载引用的节点，类似于 pending_xref。

特殊节点

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

用于“only”指令（基于标签的条件包含）的节点。

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

插入以设置后续代码块的突出显示语言和行号选项。

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

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

插入词汇表的节点。

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

插入“TOC 树”的节点。

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

标记新文件开始的节点，仅在 LaTeX 构建器中使用。

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

语法生成列表的节点。

包含 production 节点。

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

单个语法生成规则的节点。

上一页

解析器 API

下一页

日志记录 API