文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载add_enumerable_node()是 Sphinx 扩展 API 中用于扩展可编号节点enumerable node体系的入口只要把自定义 Docutils 节点注册为可枚举节点Sphinx 就会像对待figure、table、code-block一样自动为它分配编号并允许文档通过:numref:角色生成指向编号的交叉引用。本文以仓库中的测试夹具 tests/roots/test-add_enumerable_node/index.rst 为骨架结合sphinx/application.py、sphinx/registry.py、sphinx/domains/std/__init__.py的源码实现完整演示从指令定义、节点注册到numfig_format定制与最终编号渲染的全链路。读完本文你将掌握为自定义内容类型接入 Sphinx 编号系统的标准写法并理解其底层解析机制。一、先理解背景Sphinx 的 numfig 编号体系Sphinx 从 1.3 版本开始支持对图figure、表格table、代码块code-block等带标题caption的节点进行自动编号这套机制统称 numfig由三个配置项控制详见 doc/usage/configuration.rstnumfigbool默认False开启后带标题的 figure、table、code-block 会被自动编号numref角色随之启用。目前仅 HTML 与 LaTeX 构建器遵守该开关LaTeX 构建器无论是否开启都会分配编号。numfig_formatdict[str, str]默认{}把figure、table、code-block、section映射到编号的显示格式%s会被编号替换。内置默认值见 sphinx/config.py 的init_numfig_format()为numfig_format { section: Section %s, figure: Fig. %s, table: Table %s, code-block: Listing %s, }numfig_secnum_depthint默认1控制编号是否携带章节前缀。设为0时从 1 连续编号设为1时编号形如x.1、x.2其中x是章节号仅当 toctree 启用:numbered:且存在顶级章节时生效设为2则形如x.y.1。需要特别指出的是哪些节点类型参与编号并非写死在配置里而是由 Sphinx 在运行时通过一个可扩展的注册表维护——这正是add_enumerable_node()存在的意义。标准域StandardDomain内置的映射如下sphinx/domains/std/init.pyenumerable_nodes { nodes.figure: (figure, None), nodes.table: (table, None), nodes.container: (code-block, None), }映射的值是(figtype, title_getter)二元组figtype决定该节点参与哪条独立的编号序列title_getter负责从节点中提取标题文本用于:numref:的默认显示文本。二、测试夹具全景一套完整的可枚举节点示例仓库中的 tests/roots/test-add_enumerable_node/ 是一个专为验证add_enumerable_node而设计的 Sphinx 测试工程包含四个文件文件作用index.rst测试文档源展示两种自定义编号节点的用法与:numref:引用conf.py构建配置加载扩展、开启numfigenumerable_node.py扩展源码自定义指令、节点类、visitor 与注册逻辑rimg.png供 figure / my-figure 指令引用的测试图片其conf.py极为精简只做了两件关键事情extensions [enumerable_node] # 加载本地扩展模块 numfig True # 开启自动编号enumerable_node.py位于测试根目录下并通过sys.path.insert(0, str(Path.cwd().resolve()))加入导入路径因此extensions [enumerable_node]可以直接引用到它。index.rst的文档结构如下原文档全文 test-add_enumerable_node .. toctree:: :numbered: First section .. _first_figure: .. figure:: rimg.png First figure .. _first_my_figure: .. my-figure:: rimg.png First my figure .. _first_numbered_text: .. numbered-text:: Hello world .. _second_numbered_text: .. numbered-text:: Hello Sphinx Second section .. _second_my_figure: .. my-figure:: rimg.png Second my figure Reference section * first_figure is :numref:first_figure * first_my_figure is :numref:first_my_figure * second_my_figure is :numref:second_my_figure * first numbered_text is :numref:first_numbered_text * second numbered_text is :numref:second_numbered_text可以看到该文档混合了三种可编号内容内置的figure、自定义的my-figure、自定义的numbered-text并分别用.. _label:显式目标为它们打上标签最后在 Reference section 统一用:numref:交叉引用。这个结构本身就是一个绝佳的模板先定义带标签的可编号节点再用:numref:引用。三、扩展源码逐行拆解定义指令、节点与 visitorenumerable_node.py的核心是定义两种可编号内容它们分别演示了两种不同的注册姿势。3.1 自定义 figure 子类my-figure指令第一种是对内置figure的扩展通过继承nodes.figure得到一个子类节点class my_figure(nodes.figure): pass def visit_my_figure(self, node): self.visit_figure(node) def depart_my_figure(self, node): self.depart_figure(node) class MyFigure(Directive): required_arguments 1 has_content True def run(self): figure_node my_figure() figure_node nodes.image(uriself.arguments[0]) figure_node nodes.caption(text.join(self.content)) return [figure_node]要点分析my_figure直接继承nodes.figure因此在 HTML 构建器中可以复用visit_figure/depart_figure作为 visitor无需自写渲染逻辑。MyFigure指令要求 1 个位置参数图片 URI并允许带内容caption 文本在run()中构造出与内置 figure 相同结构的节点树my_figure节点下挂image子节点与caption子节点。caption 子节点是编号能否生成的关键Sphinx 的get_numfig_title()见后文默认会在可枚举节点内部查找docutils.nodes.caption或docutils.nodes.title作为标题而编号分配也依赖 caption 存在。3.2 全新节点类型numbered-text指令第二种是完全自定义的节点不继承任何内置可编号节点class numbered_text(nodes.Element): pass def visit_numbered_text(self, node): self.body.append(self.starttag(node, div)) self.add_fignumber(node) self.body.append(node[title]) self.body.append(/div) raise nodes.SkipNode def get_title(node): # NoQA: FURB118 return node[title] class NumberedText(Directive): required_arguments 1 final_argument_whitespace True def run(self): return [numbered_text(titleself.arguments[0])]要点分析numbered_text是一个纯粹的nodes.Element其渲染完全交给自定义 visitor 完成。visit_numbered_text展示了可编号节点在 HTML 输出端如何被渲染调用self.add_fignumber(node)把编号如No.1插入输出随后追加标题文本并包裹在div中最后raise nodes.SkipNode阻止 docutils 继续遍历子节点。get_title是一个title_getter从节点属性node[title]提取标题字符串供:numref:的默认显示文本使用。NumberedText指令接收一个参数并允许参数内含空白final_argument_whitespace True这正是.. numbered-text:: Hello world能一次接收整个句子作为标题的原因。四、setup()注册流程add_enumerable_node的标准调用扩展的setup()函数集中展示了add_enumerable_node的两种调用形态def setup(app): # my-figure app.add_enumerable_node( my_figure, figure, html(visit_my_figure, depart_my_figure) ) app.add_directive(my-figure, MyFigure) # numbered_label app.add_enumerable_node( numbered_text, original, get_title, html(visit_numbered_text, None) ) app.add_directive(numbered-text, NumberedText) app.config.numfig_format.setdefault(original, No.%s)对my_figure把节点注册到系统内置的figure编号序列figtypefigure意味着它与普通 figure共享同一套编号因此最终渲染效果是Fig. 1、Fig. 2、Fig. 3连续递增。对numbered_text注册到全新的自定义编号类型originalfigtypeoriginal拥有独立编号序列同时传入title_getterget_title并定义 HTML visitor 元组(visit_numbered_text, None)depart 为None因为 visit 阶段通过SkipNode直接消费了节点。最后通过app.config.numfig_format.setdefault(original, No.%s)为新的 figtype 配置编号显示格式效果是编号渲染为No.1、No.2。这里用到setdefault而非直接赋值是为了允许用户在项目conf.py中覆盖扩展设定的默认格式——这是扩展开发中的良好实践。五、add_enumerable_nodeAPI 官方定义与参数语义Sphinx.add_enumerable_node()的完整签名与 docstring 定义在 sphinx/application.pydef add_enumerable_node( self, node: type[Element], figtype: str, title_getter: TitleGetter | None None, override: bool False, **kwargs: tuple[_NodeHandler, _NodeHandler], ) - None: Register a Docutils node class as a numfig target.各参数语义如下node要注册的 Docutils 节点类。注册后 Sphinx 会自动为其编号文档中可通过:numref:引用它。figtype可枚举节点的类型标识每种 figtype 拥有独立的编号序列。系统内置figure、table、code-block三种你可以把自定义节点挂到这些默认序列下如测试中的my_figure也可以传入全新 figtype如测试中的original开创新的编号序列。title_getter可调用对象接收节点实例并返回其标题字符串。该标题用作:numref:交叉引用numref无显式标题时的默认显示文本。默认行为是 Sphinx 自动在节点内部查找docutils.nodes.caption或docutils.nodes.title子节点作为标题。**kwargs各构建器的 visitor 函数语义与add_node()完全一致如html(visit, depart)、latex(...)。override若为True即使同名节点已注册也会强制安装默认为False。在实现层面add_enumerable_node拆成两步先调用self.registry.add_enumerable_node(node, figtype, title_getter, overrideoverride)登记编号信息再调用self.add_node(node, overrideoverride, **kwargs)注册节点与各构建器 visitor。底层登记逻辑见 sphinx/registry.pydef add_enumerable_node(self, node, figtype, title_getterNone, overrideFalse): if node in self.enumerable_nodes and not override: raise ExtensionError(__(enumerable_node %r already registered) % node) self.enumerable_nodes[node] (figtype, title_getter)也就是说同一节点类重复注册会抛出ExtensionError除非显式传入overrideTrue。注册表是Sphinx应用实例级的属性self.enumerable_nodes它在构建时被合并进 StandardDomain 的实例映射中见 sphinx/domains/std/init.pyself.enumerable_nodes copy(self.enumerable_nodes) for node, settings in env._registry.enumerable_nodes.items(): self.enumerable_nodes[node] settings六、底层编号与引用解析原理add_enumerable_node只是入口编号真正产生作用依赖 StandardDomain 中的三组逻辑全部位于 sphinx/domains/std/init.py。6.1 判定与取标题is_enumerable_node/get_enumerable_node_type/get_numfig_titledef is_enumerable_node(self, node: Node) - bool: return node.__class__ in self.enumerable_nodes def get_enumerable_node_type(self, node: Node) - str | None: if isinstance(node, nodes.section): return section elif (isinstance(node, nodes.container) and literal_block in node and _has_child(node, nodes.literal_block)): return code-block else: figtype, _ self.enumerable_nodes.get(node.__class__, (None, None)) return figtype def get_numfig_title(self, node: Node) - str | None: if self.is_enumerable_node(node): elem cast(Element, node) _, title_getter self.enumerable_nodes.get(elem.__class__, (None, None)) if title_getter: return title_getter(elem) else: for subnode in elem: if isinstance(subnode, (nodes.caption, nodes.title)): return clean_astext(subnode) return None这段代码清晰地印证了前文的论述注册表按节点类的精确匹配node.__class__ in ...判定因此继承自nodes.figure的my_figure是独立条目但共享figure编号序列get_enumerable_node_type对section与带literal_block子节点的container即带标题的 code-block做了特殊判定其余一律查注册表get_numfig_title优先使用注册时提供的title_getter如get_title否则在节点内查找caption/title子节点——这就是必须给可编号节点带标题的原因。6.2:numref:的解析编号获取与格式替换当文档中出现:numref:first_numbered_text 时Sphinx 走StandardDomain.resolve_xref→_resolve_numref_xref链路sphinx/domains/std/init.py核心步骤为通过标签查找到目标节点调用get_enumerable_node_type得到 figtype若 figtype 不是section且env.config.numfig is False输出警告numfig is disabled. :numref: is ignored.并放弃生成引用调用get_fignumber(env, builder, figtype, docname, target_node)从env.toc_fignumbers[docname][figtype][figure_id]取出编号sphinx/domains/std/init.py若节点没有分配编号如位于 orphan 文档会抛出ValueError并被捕获转为警告Failed to create a cross reference. Any number is not assigned: ...取numfig_format中该 figtype 对应的格式串按新旧两种风格做替换新风格格式串含{name}或{number}title.format(namefigname, numberfignum)旧风格如No.%s、Fig. %stitle % fignum最终生成addnodes.number_reference节点作为交叉引用。值得注意的边界如果格式串含{name}但目标节点没有标题figname is NoneSphinx 会警告the link has no caption: ...如果numfig_format未给某 figtype 定义格式env.config.numfig_format.get(figtype, )返回空串警告numfig_format is not defined for %s。这些警告文案在 sphinx/locale/ 各语言目录的.po文件中均有对应翻译条目。七、测试验证编号结果的自动化断言该夹具由 tests/test_builders/test_build_html.py 中的test_enumerable_node测试驱动它对 HTML 构建产物index.html做了 XPath 断言pytest.mark.parametrize( (path, check, be_found), [ (FIGURE_CAPTION //span[classcaption-number], Fig. 1, True), (FIGURE_CAPTION //span[classcaption-number], Fig. 2, True), (FIGURE_CAPTION //span[classcaption-number], Fig. 3, True), (.//div//span[classcaption-number], No.1 , True), (.//div//span[classcaption-number], No.2 , True), (.//li/p/a/span, Fig. 1, True), (.//li/p/a/span, Fig. 2, True), (.//li/p/a/span, Fig. 3, True), (.//li/p/a/span, No.1, True), (.//li/p/a/span, No.2, True), ], ) pytest.mark.sphinx(html, testrootadd_enumerable_node, srcdirtest_enumerable_node) def test_enumerable_node(app, cached_etree_parse, path, check, be_found): app.build() check_xpath(cached_etree_parse(app.outdir / index.html), index.html, path, check, be_found)这些断言精确地验证了本文的全部核心结论编号共享文档中三个 figure 系节点1 个内置figure 2 个自定义my-figure的编号分别为Fig. 1、Fig. 2、Fig. 3——证明注册到figurefigtype 的自定义节点与内置 figure 共享编号序列独立编号序列两个numbered-text节点输出No.1、No.2——证明original是全新且独立的编号序列引用渲染Reference section 中所有:numref:均被解析为带编号文本的链接Fig. 1等出现在li/p/a/span中caption 编号标记HTML 输出中的编号位于span.caption-number内。若要亲自复现可在仓库根目录以该夹具为源目录执行 Sphinx 构建如sphinx-build -b html tests/roots/test-add_enumerable_node 输出目录并观察index.html中Fig. 1、No.1等编号的实际输出。八、实战要点与常见坑结合测试夹具与源码为实际扩展开发提炼以下要点节点必须有标题来源要么在节点内部构造caption/title子节点内置默认查找路径要么在注册时提供title_getter否则:numref:的默认显示文本与{name}占位符将无法工作。figtype 决定编号是否独立挂到figure/table/code-block下即与内置节点共享编号新建字符串 figtype 则开启独立编号序列。注意 figtype 本身必须先在numfig_format中有对应的格式串可在扩展中setdefault如No.%s否则引用会退化为空文本并告警。visitor 中调用self.add_fignumber(node)HTML 端若要渲染编号须在 visit 函数中显式调用add_fignumber见visit_numbered_text编号随后以span.caption-number形式输出。重复注册会抛错registry.py对同一节点类二次注册默认抛出ExtensionError需要强制覆盖时必须传overrideTrue。numfig开关的全局影响numfig False默认时所有:numref:引用都会被忽略并告警因此开启该特性的扩展应提示用户同时设置numfig True。章节前缀编号是否带章节前缀由numfig_secnum_depth与 toctree 的:numbered:共同决定——本夹具的 toctree 恰好带:numbered:且numfig_secnum_depth默认值为 1但文档中 figure 均在二级标题下且无三级嵌套因此测试断言只验证了不带前缀的纯序号。从 1.4 版本起见 doc/changes/1.4.rst 的变更记录 Add Sphinx.add_enumerable_node() to add enumerable nodes for numfigadd_enumerable_node已成为扩展编写者让自定义内容类型融入 Sphinx 编号体系的标准途径。以本测试夹具为蓝本你可以为任意自定义指令如示例图、术语卡片、告警块快速接入自动编号与:numref:引用让文档的交叉引用体系真正统一、可维护。赞分享文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载相关推荐Sphinx 图表编号机制深度解析numfig 配置、:numref: 交叉引用与章节前缀编号实战Sphinx 图表编号机制深度解析 numfig 配置、 :numref: 交叉引用与章节前缀编号实战 导读 本文围绕 Sphinx 文档生成器的自动编号体系文档开发工具Sphinx C 域交叉引用角色cpp:class / cpp:func / cpp:any与括号处理实战解析Sphinx C 域交叉引用角色cpp:class / cpp:func / cpp:any与括号处理实战解析 本篇指南围绕 Sphinx 仓库中 C文档开发工具Sphinx autosectionlabel 扩展详解用章节标题直接创建交叉引用Sphinx autosectionlabel 扩展详解用章节标题直接创建交叉引用 autosectionlabel 是 Sphinx 官方自带的扩展它让你文档开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
