文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载only指令是 Sphinx 中实现按条件包含文档内容的核心工具它允许作者用简单的标签表达式如html and draft在同一份源文档中为不同输出目标HTML、LaTeX、Text或不同构建场景裁剪内容。本文基于 Sphinx 源码仓库中该功能的官方文档、指令实现与专项测试完整讲解only的语法、标签定义方式、底层求值机制与嵌套章节的处理逻辑帮助读者掌握从写条件到看效果的完整链路。一、only指令的语法与表达式only指令的完整语法为.. only:: expression 仅在表达式为真时才会出现在输出中的内容其中expression由**标签tag**和布尔运算符构成例如.. only:: html and draft表达式规则源自 Sphinx 用户文档未定义的标签为假已定义的标签为真支持布尔表达式与括号例如(latex or html) and draft标签必须符合 Python 标识符语法仅能由字母A–Z、下划线_组成且首字符之后才能出现数字0–9非 ASCII 字符需遵循 Python 标识符规则。需要特别注意的是官方文档明确指出该指令的设计目的是控制文档内容并不适合用来控制章节、标签label等结构性元素。这一点与下文要分析的嵌套章节测试形成了有趣的对照。二、标签从哪里来三种定义途径only表达式中使用的标签有且仅有三种来源Sphinx 会将其统一收集到Tags对象中实现见 sphinx/util/tags.py。1. 命令行选项-t tag/--tag tag在调用sphinx-build时可以通过-t短选项或--tag长选项Sphinx 7.3 起支持定义任意标签sphinx-build -b html -t draft -t review src/ build/命令行选项的完整说明见 sphinx-build 手册该选项从 Sphinx 0.6 开始提供专门服务于only指令的标签判断。2.conf.py中的tags对象conf.py中暴露了一个名为tags的特殊对象见 配置文档可以在配置阶段动态增删标签tags.add(draft) # 增加标签 tags.remove(review) # 移除标签 if draft in tags: # 查询标签是否已设置 ...需要注意builder 的名称和格式标签在读取conf.py时尚未生效因此不能在conf.py中查询html、latex这类自动标签。3. Builder 自动注入的内置标签Sphinx 会将当前 builder 的**格式format与名称name**自动设为标签Sphinx 0.6 起1.2 起增加前缀形式示例 Builder自动生效的标签htmlhtml、format_html、builder_htmlepubhtml、epub、format_html、builder_epublatexlatex、format_latex、builder_latextexttext、format_text、builder_text即每个 builder 至少注入三个标签format、format_format与builder_name。这类标签在conf.py读取之后才设置所以在配置文件中不可用。三、源码视角only指令的完整执行链路only指令并不是简单的解析时删掉内容而是一个跨阶段的两步过程。1. 解析阶段创建only节点并暂存表达式指令类Only定义在 sphinx/directives/other.py其核心行为是将参数中的表达式原样存入addnodes.only节点的expr属性在docutils的状态机中暂存当前文档的标题样式与章节层级memo.title_styles、memo.section_level再以nested_parse(..., match_titlesTrue)解析指令内容若指令内容中出现了与文档标题样式匹配的章节标题则通过一系列深度计算current_depth、nested_depth、n_sects_to_raise把嵌套章节提升到文档树中的正确层级这正是only内容里的章节能正常融入文档结构的底层实现最后通过directives.register_directive(only, Only)注册为内建指令sphinx/directives/other.py#L428。2. 后处理阶段按标签求值并替换节点解析阶段并不判断真假真正的筛选发生在构建阶段的后处理中。OnlyNodeTransform默认优先级 50见 sphinx/transforms/post_transforms/init.py遍历文档树调用process_only_nodesprocess_only_nodes(self.document, self.env._tags)process_only_nodessphinx/util/nodes.py的实现逻辑非常简洁遍历所有addnodes.only节点若tags.eval_condition(node[expr])为真则用其子节点原位替换only节点内容被保留并提升若为假则替换为一个comment()节点——注释节点保证了 docutils 的 id 传递机制不会因节点消失而抛出 Losing ids 异常若求值过程抛出异常例如表达式语法非法则记录一条exception while evaluating only directive expression警告并保守地保留内容返回True。四、表达式求值基于 Jinja2 语法子集的安全布尔运算标签表达式的求值由 sphinx/util/tags.py 中的BooleanParser完成。它复用 Jinja2 的解析器但做了严格约束只允许条件表达式与二元运算符and、or、not并支持括号与三元条件表达式。Tags.eval_condition的具体行为如下先查_condition_cache缓存相同表达式只解析求值一次用BooleanParser解析表达式若解析后还有剩余 token 则抛出chunk after expression错误递归求值 ASTAnd/Or/Not对应逻辑运算Name节点则判断该名字是否存在于self._tags集合中sphinx/util/tags.py#L86-L100。因此表达式中的每个标识符本质上就是标签集合的成员查询not nonexisting_tag之所以为真正是因为nonexisting_tag不在集合中未定义即为假取反即为真。五、专项测试解析嵌套章节在only中的层级处理仓库中针对本主题有一个专门的测试根目录 tests/roots/test-directive-only其index.rst通过 toctree 挂载了被测文档only.rstconf.py中仅设置project与exclude_patterns [_build]。被测文档 only.rst 系统性地覆盖了各种场景only中包裹章节、only中包裹子章节、多个only相邻出现、only中再嵌套only、以及only中直接包裹文档级标题装饰线等。例如1. Sections in only directives .. only:: nonexisting_tag Skipped Section --------------- Should not be here. .. only:: not nonexisting_tag 1.1. Section ------------ Should be here.由于nonexisting_tag未定义假not nonexisting_tag为真因此只有标记 Should be here 的内容会进入最终输出标记 Should not be here 的内容在后处理阶段被替换为注释节点。对应的测试用例 test_directive_only.py 验证了最终文档树的结构pytest.mark.sphinx(text, testrootdirective-only) def test_sectioning(app): app.build(filenames[app.srcdir / only.rst]) doctree app.env.get_doctree(only) app.env.apply_post_transforms(doctree, only) ... assert len(parts) 4 # 期望恰好 4 个文档级标题测试断言最终恰好生成4 个文档级标题only.rst中以装饰的文档级标题共有 4 个1.、2.、3.、4.其中包裹在only:: nonexisting_tag中的两个文档级标题Skipped document level heading会被剔除而包裹在not nonexisting_tag中的两个文档级标题2.、4.会保留。辅助函数_test_sections还递归断言每个子章节的编号顺序与层级深度完全符合源文档的编号体系如1.→1.1.→1.1.1.从而验证了Only.run()中嵌套章节提升逻辑的正确性。六、实战示例与使用建议多目标输出裁剪同一份文档面向 HTML 与 LaTeX 输出时可用 builder 标签做差异化.. only:: latex 本段内容仅出现在 LaTeX 输出中。 .. only:: html 本段内容仅出现在 HTML 输出中。与自定义标签配合的发布流程在持续构建中加入-t参数即可一键切换文档形态# 草稿模式构建 sphinx-build -b html -t draft src/ build/draft/ # 正式发布构建 sphinx-build -b html src/ build/release/建议善用not与括号如.. only:: not (latex or html)可精确表达非 HTML 且非 LaTeX避免用它控制结构性元素官方文档明确警告only只适合控制内容本身不适合控制章节、交叉引用标签等结构详见 directives.rst 警告说明注意求值时机builder 内置标签在conf.py之后才注入配置文件中不要查询它们表达式错误会保守放行一旦表达式求值异常Sphinx 会输出警告并保留内容而非静默丢弃调试时留意构建日志中的exception while evaluating only directive expression提示。七、小结only指令从语法上看只是一个带表达式的块级指令但背后串联了指令注册sphinx/directives/other.py、标签集合管理sphinx/util/tags.py、后处理筛选sphinx/transforms/post_transforms/init.py与章节层级提升四层机制。理解这条链路后你不仅能写出正确的条件文档还能预判only与章节编号、toctree、交叉引用交互时的行为边界从而更安全地把它用在多格式发布与多阶段评审的文档工作流中。赞分享文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载相关推荐Nuclide模板条件包含文件内容条件插入Nuclide模板条件包含文件内容条件插入 在Nuclide开发环境中模板条件包含功能允许开发者根据特定条件动态插入文件内容这一机制广泛应用于文档生成和界开发工具Sphinx ifconfig 扩展基于 conf.py 配置值条件化文档内容Sphinx ifconfig 扩展基于 conf.py 配置值条件化文档内容 doc/usage/extensions/ifconfig.rst 官方文档所文档开发工具x64dbg 脚本条件分支指令 Jxx/IFxx 完全指南基于 cmp 标志的标签跳转机制与源码级实现解析x64dbg 脚本条件分支指令 Jxx/IFxx 完全指南基于 cmp 标志的标签跳转机制与源码级实现解析 导读 Jxx jmp、je、jne、jb、ja、逆向工程调试器开发工具应用安全上一篇轻松应对键盘遮挡问题IHKeyboardAvoiding下一篇推荐使用Avvvatars - 独特的React头像占位符组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考