文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载Sphinx 在文档写作过程中经常需要临时记录此处待补充接口待实现之类的待办事项。sphinx.ext.todo扩展正是为此设计它通过todo指令把待办事项以醒目提示块admonition的形式写入文档并通过todolist指令把整个项目的所有待办事项汇总到任意一个页面统一管理、按需开关输出。本文以仓库中tests/roots/test-ext-todo/测试根文档为实例结合 扩展实现源码 与 官方用户文档完整讲解该扩展的启用方法、两个指令的用法、三个配置项的作用与取值以及事件钩子与底层运行原理读完即可在自己的 Sphinx 项目中落地一套可开关、可汇总、可告警的 TODO 管理方案。一、从测试根文档看该扩展的使用场景仓库中的 tests/roots/test-ext-todo/index.rst 是专门为验证sphinx.ext.todo而准备的测试根文档testroot全文只有 10 行却完整勾勒出该扩展的核心用法test for sphinx.ext.todo .. toctree:: foo bar .. todolist:: .. todolist::这个文档揭示了三个关键信息todolist指令是一个零参数、零内容的指令直接写.. todolist::即可它会被渲染成全项目 TODO 汇总清单todolist可以重复出现多次该测试文档刻意写了两次用于验证重复指令的健壮性测试文件tests/test_extensions/test_ext_todo.py中test_todo_valid_link正是利用这一点断言每个todolist都生成了回链该扩展的典型应用场景是配合toctree在索引页或独立维护页面汇总全书的待办事项而待办事项本身分散写在各个子文档如foo.rst、bar.rst中。同目录下的 foo.rst 和 bar.rst 展示了todo指令的实际写法.. todo:: todo in foo .. py:function:: hello() :param bug: https://github.com/sphinx-doc/sphinx/pull/5800 .. todo:: todo in param field.. todo:: todo in bar可以看到todo指令像note等 admonition 指令一样使用参数即待办内容它甚至可以嵌套在:param:字段描述等深层结构中这一点在foo.rst的py:function示例里得到了验证。二、启用扩展与最小可运行配置sphinx.ext.todo是 Sphinx 自带的扩展启用方式与所有内置扩展一致在项目的conf.py中把sphinx.ext.todo加入extensions列表。测试根文档的 conf.py 是它的最小配置extensions [sphinx.ext.todo]仅此一行即可让todo与todolist两个指令生效指令注册位于 setup() 函数 中的app.add_directive(todo, Todo)与app.add_directive(todolist, TodoList)。一个完整的可运行最小项目结构如下my-docs/ ├── conf.py # extensions [sphinx.ext.todo] ├── index.rst # .. todolist:: 汇总页 ├── foo.rst # .. todo:: 具体待办 └── bar.rst # .. todo:: 具体待办构建方式与普通文档一致在项目根目录执行sphinx-build -b html source build或make html。关于构建与命令行参数的细节可参考 doc/usage/quickstart.rst。三、todo指令把待办写成醒目的提示块todo指令的用法与note、warning等 admonition 指令完全一致正文即待办描述.. todo:: 补充安装步骤的截图 .. todo:: 该章节的 API 表格待完善它的输出形式由实现类Todo决定见 Todo.run()节点类型继承自nodes.Admonition即按提示块渲染自动插入Todo标题未显式指定class选项时HTML 输出的 class 默认为admonition-todo便于 CSS 定制class选项自 1.3.2 版本开始支持每个todo节点会记录来源文档名todo[docname]并注册为显式目标note_explicit_target从而获得锚点 ID供todolist生成回链使用。在 HTML 构建todo_include_todosTrue时中foo.html中的.. todo:: todo in foo会被渲染为类似如下的结构断言来自 test_todop classadmonition-titleTodo/p ptodo in foo/p3.1 在字段描述等复杂位置使用foo.rst展示了todo指令可以出现在py:function的参数描述里.. py:function:: hello() :param bug: https://github.com/sphinx-doc/sphinx/pull/5800 .. todo:: todo in param field这表示待办可以就近写在任何需要提醒的位置而不必集中在文末。测试断言验证了该场景同样会被收集进todolisttest_todo中todo-defined事件共捕获 3 个待办todo in foo、todo in bar、todo in param field。四、todolist指令一键汇总全项目待办todolist是本文核心场景对应的指令——它不写任何参数或正文出现的位置即全项目 TODO 汇总表的渲染位置.. todolist::其实现TodoList.run()只是简单地插入一个空的todolist节点真正的填充发生在后续的doctree-resolved事件处理阶段见下文底层实现原理。汇总清单中每一条 TODO 都附带一个指向原始位置的回链默认显示为如下句式原始条目位于foo.rst第 5 行。→ [original entry]具体文案逻辑见 create_todo_reference()当todo_link_only为False默认时回链描述包含来源文件路径与行号(The original entry is located in %s, line %d.)这正是TodoListProcessor通过todo.source与todo.line拼出的信息当todo_link_only为True时只输出original entry即original entry不显示文件路径和行号适合把清单页做得更简洁回链的refuri由builder.get_relative_uri(docname, todo[docname]) # todo[ids][0]生成指向待办所在文档的具体锚点对无法确定 URI 的输出如部分 LaTeX 场景则跳过该回链except NoUri。同时todolist汇总的待办内容会深拷贝todo.deepcopy()到清单页并在拷贝上重新解析内部交叉引用resolve_reference会把pending_xref的refdoc改写成清单页所在文档再调用env.resolve_references保证汇总页中的引用也能正确解析。五、三个配置项开关、精简、告警该扩展的全部行为由三个布尔配置项控制官方文档 doc/usage/extensions/todo.rst 与源码 setup() 中的注册保持一致配置项类型默认值作用todo_include_todosboolFalse为True时todo与todolist才会真正产生输出为False时两者都不渲染任何内容todo_emit_warningsboolFalse为True时每发现一条 TODO 都在构建时输出WARNING: TODO entry found: ...告警自 1.5 版本引入todo_link_onlyboolFalse为True时todolist汇总项不显示来源文件路径与行号只保留回链自 1.4 版本引入典型组合配置示例extensions [sphinx.ext.todo] # 正式发布版关闭 TODO 输出 todo_include_todos False # 开发阶段开启构建时提醒还有哪些未完成 todo_emit_warnings True5.1todo_include_todos的一刀切开关这是最重要的开关。当其为False默认时文档源码中的todo与todolist指令完全不产生输出相当于待办在发布文档中隐形但源码依然保留下次开启即可恢复。测试 test_todo_not_included 专门验证了这一点在todo_include_todos False下index.html与foo.html中均不包含任何 Todo 输出但todo-defined事件与告警照常触发——说明收集与输出是解耦的。5.2todo_emit_warnings的遗漏提醒当其为True时TodoDomain.process_doc()见 sphinx/ext/todo.py在遍历每篇文档时对每个todo_node输出形如TODO entry found: todo in foo的警告并附上位置信息。这非常适合在 CI 中配合-W警告转错误使用一旦有人提交了带 TODO 的文档构建即失败从而强制清理未完成内容。5.3todo_link_only的精简模式当其为True时汇总清单只保留original entry回链隐藏文件路径与行号适用于对外展示的精简清单页。六、事件钩子todo-defined自 1.5 版本起该扩展在setup()中注册了todo-defined事件app.add_event(todo-defined)。每发现一条待办TodoDomain.process_doc()就会触发该事件回调接收两个参数app当前 Sphinx 应用实例node本次定义的sphinx.ext.todo.todo_node节点。这为二次开发提供了极大的灵活性例如把 TODO 统计到外部系统、写入日志或生成报表。测试 test_todo 中的用法即是最佳示范def on_todo_defined(app, node): todos.append(node) app.connect(todo-defined, on_todo_defined)七、底层实现原理从源码看 TODO 是如何被收集—汇总的sphinx.ext.todo的运行机制清晰分为四个层次全部实现在 sphinx/ext/todo.py 中指令注册setup()将todo注册为Todo指令继承SphinxAdmonition按提示块处理将todolist注册为TodoList指令仅插入空节点占位并注册TodoDomain域名域收集TodoDomain维护todos数据结构docname - [todo_node, ...]。process_doc()在每篇文档处理阶段把该文档的所有todo_node追加进域数据同时触发todo-defined事件、按需发出告警clear_doc()与merge_domaindata()则负责增量重建与并行构建时的数据合并这正是parallel_read_safe True的保障见setup()返回值汇总填充setup()通过app.connect(doctree-resolved, TodoListProcessor)把汇总逻辑挂到构建后期。TodoListProcessor.process()会做三件事若todo_include_todos为False直接移除文档树中所有todolist占位节点若为True遍历域中收集到的全部待办逐个深拷贝、清空原锚点 ID、重解析引用并追加original entry回链用填充后的内容替换占位节点。多格式输出todo_node按格式分别注册了翻译器——HTML/文本/man/texinfo 复用visit_todo_nodetodo_include_todos为假时抛nodes.SkipNode跳过渲染LaTeX 走latex_visit_todo_node输出\begin{sphinxtodo}环境并处理no_latex_floats计数与表格兼容问题。这段链路解释了前文所有行为为什么todolist无需参数、为什么汇总内容与原文位置解耦、为什么 LaTeX 下回链可能退化为纯文本NoUri分支。八、测试验证行为即契约仓库用 tests/test_extensions/test_ext_todo.py 固化该扩展的行为契约三个测试分别覆盖三条关键路径test_todoHTML、todo_include_todosTrue断言index.html的汇总清单包含来自foo与bar的两条待办foo.html内联渲染出todo in foo与嵌套在参数字段里的todo in param field同时todo_emit_warningsTrue触发两条TODO entry found告警todo-defined事件恰好捕获 3 个节点test_todo_not_includedHTML、todo_include_todosFalse断言所有输出中均无 Todo 渲染但告警与事件照常发生验证收集与渲染解耦test_todo_valid_linkLaTeX、todo_include_todosTrue因为测试根文档index.rst写了两次todolist断言汇总回链\hyperref[...]{original entry}在 LaTeX 输出中出现 4 次2 条待办 × 2 处清单且每条回链都恰好对应一个\label目标——这曾是一个真实缺陷sphinx-doc/sphinx#1020回链目标缺失测试确保其不再回归。九、落地实践建议把该扩展投入真实项目时推荐如下工作流在conf.py中启用扩展开发阶段设置todo_include_todos True、todo_emit_warnings True发布版本切换为False在文档索引页或专门的任务看板页放置.. todolist::作为全项目未完成工作的单一入口写作过程中就近在对应章节用.. todo::记录缺口配合todo_emit_warnings在 CI 中提醒若需深度定制如把待办同步到 issue 跟踪系统监听todo-defined事件即可获得每个待办的节点对象输出格式上HTML 下通过默认 classadmonition-todo定制样式LaTeX 下使用sphinxtodo环境渲染。该扩展自 0.5 版本引入至今仍在迭代todo_link_only与todo_emit_warnings分别于 1.4、1.5 加入其开关控制输出、域统一收集、事件对外扩展的设计是理解 Sphinx 扩展机制指令 域 事件 doctree 变换的绝佳入门案例。赞分享文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载相关推荐Sphinx todo 扩展完全指南用 sphinx.ext.todo 管理文档中的 TODO 事项Sphinx todo 扩展完全指南用 sphinx.ext.todo 管理文档中的 TODO 事项 todo 是 Sphinx 官方内置扩展 sphinx文档开发工具Sphinx 的 todo 扩展用 .. todo:: 指令在文档中管理待办事项Sphinx 的 todo 扩展用 .. todo:: 指令在文档中管理待办事项 导读 本文围绕 Sphinx 仓库中 tests/roots/test ex文档开发工具eSearch 源码跑起来截屏、离线 OCR、录屏本地怎么装eSearch 源码跑起来截屏、离线 OCR、录屏本地怎么装 eSearch 是一款基于 Electron跨平台桌面应用框架的屏幕工具把截屏、离线 O桌面应用OCR屏幕录制视频处理图像处理上一篇TVM 安装完全指南从源码编译、Docker 环境到 Python 包的一站式上手下一篇trackerslist75 个公共 BT Tracker 列表让下载提速的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考