Sphinx 添加的 Doctree 节点类

特定领域对象描述的节点

顶级节点

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

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)

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

它应该仅作为 desc_signature 的子项使用,且 is_multiline 设置为 True.为应获取永久链接的行设置 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)

用于”返回”注解的节点（类似于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.它的值是一个由 (entrytype, entryname, target, ignored, key) 组成的 5 元组列表.

entrytype 是 “single”, “pair”, “double”, “triple” 之一.

key 是用于一般索引页的分类字符（通常是单个字符）.有关详细信息,请参见:术语表 和 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

如果交叉引用解析器成功解析了交叉引用,那么它会将 pending_xref 重写为:

<reference>
    <literal>
        StringIO

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

<reference>
    <literal>
        io.StringIO

pending_xref_condition 节点应该有 condition 属性.域可以将它们各自的条件存储到该属性中,以在解析阶段过滤内容.作为保留的条件名称,``condition=”*”`` 用于解析失败的回退.此外,作为推荐的条件名称,``condition=”resolved”`` 表示在 intersphinx 模块中解析成功.

Added in version 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)

用于插入”目录树”的节点.

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)

单个语法产生规则的节点.

Previous

解析器 API

Next

Logging API