文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载本篇指南以 Sphinx 官方测试根目录 tests/roots/test-directive-code/index.rst 为核心案例完整讲解 reStructuredText 中code-block代码块与literalinclude字面包含两大指令的语法、选项、运行效果与底层实现。读完本文你将掌握如何用:linenos:、:emphasize-lines:、:dedent:、:lines:、:pyobject:等选项精确控制代码展示并能在 Sphinx 源码 sphinx/directives/code.py 中定位每个选项的实现逻辑。从测试文档看两大代码指令的基本用法测试根目录test-directive-code是 Sphinx 自测code指令的专用工程其入口文档 tests/roots/test-directive-code/index.rst 用两个最小示例直接展示了本主题的核心骨架code-block指令书写一段 Ruby 代码并通过:linenos:选项开启行号显示.. code-block:: ruby :linenos: def ruby? false endliteralinclude指令将外部文件 tests/roots/test-directive-code/literal.inc 以字面文本形式原样包含进文档并指定高亮语言为 Python.. literalinclude:: literal.inc :language: python这两个指令分别对应 sphinx/directives/code.py 中的CodeBlock类和 sphinx/directives/code.py 中的LiteralInclude类二者在指令注册时由setup()统一登记sphinx/directives/code.pydirectives.register_directive(highlight, Highlight) directives.register_directive(code-block, CodeBlock) directives.register_directive(sourcecode, CodeBlock) # code-block 的旧别名 directives.register_directive(literalinclude, LiteralInclude)值得注意的是code-block与旧式指令名sourcecode指向同一个实现类因此二者完全等价。测试 tests/test_directives/test_directive_code.py 通过 XML 构建器验证code-block渲染后的literal_block节点文本与源码内容逐字符一致即 def ruby?\n false\n end。code-block代码块指令的完整选项解析CodeBlock的option_specsphinx/directives/code.py决定了它支持的全部选项选项类型作用:language:位置参数字符串指定高亮语言如ruby、python、c:force:标志强制高亮即使代码与语言不符也不警告:linenos:标志显示行号:lineno-start:整数行号起始值:emphasize-lines:行号规格高亮指定行如6-7, 16-19, 29-:dedent:整数或空去除每行指定数量的缩进无参数时自动去除公共缩进:caption:字符串为代码块添加标题可用于numfig编号:class:类名列表附加 CSS 类名:name:字符串为代码块命名供交叉引用语言参数与高亮机制code-block的第一个参数即高亮语言。若省略该参数CodeBlock.run()会回退到“当前高亮语言”sphinx/directives/code.pyliteral[language] ( self.env.current_document.highlight_language or self.config.highlight_language )“当前高亮语言”由两种途径设定一是highlight指令如.. highlight:: python3二是配置项highlight_language默认default。测试 tests/roots/test-directive-code/highlight.rst 与 tests/test_directives/test_directive_code.py 验证了这一回退链未指定语言的块使用defaulthighlight:: python3之后的块自动变为python3而显式指定python2的块始终保持自身语言。highlight指令本身在 sphinx/directives/code.py 实现除语言参数外还支持:force:与:linenothreshold:两个选项后者用于控制“代码行数达到多少时才显示行号”。:linenos: 与 :lineno-start: 行号控制:linenos:是标志选项只要存在即显示行号:lineno-start:则同时隐式开启行号并指定起始编号。实现上二者都会在节点上打上linenos标记sphinx/directives/code.pyif linenos in self.options or lineno-start in self.options: literal[linenos] True:lineno-start:的取值还会写入highlight_args[linenostart]sphinx/directives/code.py最终交给 Pygments 渲染。例如 tests/roots/test-directive-code/linenos.rst 中的:lineno-start: 200在 HTML 输出中第一行行号即显示为200由 tests/test_directives/test_directive_code.py 断言。:emphasize-lines: 高亮指定行:emphasize-lines:接受逗号分隔的行号范围如6-7, 16-19, 29-支持“从第 29 行到末尾”的开区间写法。其解析由parse_line_num_spec位于 sphinx/util/_lines.py完成越界行号会触发警告但不中断构建sphinx/directives/code.py。测试 tests/roots/test-directive-code/emphasize.rst 展示了真实用法LaTeX 构建结果中对应\fvset{hllines{, 6, 7, 16, 17, 18, 19, 29, 30, 31,}}tests/test_directives/test_directive_code.py。:dedent: 与缩进处理dedent_lines()sphinx/directives/code.py是缩进处理的核心函数指定数值:dedent: 4每行截掉 4 个字符宽度若某行实际缩进不足会发出non-whitespace stripped by dedent警告无参数:dedent:等价于 Python 的textwrap.dedent()自动剥离所有行公共的最小缩进。测试 tests/roots/test-directive-code/dedent.rst 系统验证了各情形dedent: 0是空操作、dedent: 4从 6 空格缩进中剥掉 4 格得到 2 格缩进、无参数时自动去除公共缩进tests/test_directives/test_directive_code.py 逐条断言了 6 种组合的输出文本。:caption: 与 :name: 标题与交叉引用:caption:会为代码块生成带编号的标题Listing 1配合numfig True测试工程在 tests/roots/test-directive-code/conf.py 中开启自动编号。:name:则为代码块命名使:numref:与:ref:可以引用它。标题包装逻辑见container_wrapper()sphinx/directives/code.py。caption.rst 演示了完整用法See :numref:name *test* rb and :ref:Ruby name *test* rb. .. code-block:: ruby :caption: caption *test* rb def ruby? false endHTML 输出为span classcaption-numberListing 1 /spantests/test_directives/test_directive_code.pyLaTeX 输出则为\sphinxSetupCaptionForVerbatim{...}与可交叉引用的 labeltests/test_directives/test_directive_code.py。:class: 与 :force::class: foo bar将 CSS 类附加到literal_block节点sphinx/directives/code.py用于自定义样式测试见 classes.rst:force:告诉高亮器“即使代码无法用该语言解析也不要降级或警告”force.rst 用它包裹明显不是 Python 的内容并断言构建过程零警告tests/test_directives/test_directive_code.py。literalinclude从外部文件包含代码literalinclude的核心价值是文档与源码保持单一事实来源你只需维护真实源码文件文档自动同步。它在 sphinx/directives/code.py 中实现选项比code-block更丰富选项作用:language:指定高亮语言:linenos:/:lineno-start:/:lineno-match:行号显示、起始值、与源文件行号对齐:lines:按行号规格选取片段如5-9、1,3,5:pyobject:提取 Python 对象类/函数定义:start-after:/:start-at:/:end-before:/:end-at:按文本标记截取片段:prepend:/:append:在片段前后插入文本:dedent:去除缩进:tab-width:将制表符展开为指定宽度:diff:显示当前文件与另一文件的统一差异:encoding:指定读取编码:emphasize-lines:/:caption:/:class:/:name:与 code-block 相同的展示类选项行号三兄弟linenos、lineno-start、lineno-match:linenos:无条件显示行号:lineno-start: N显示行号并从 N 起编:lineno-match:让行号与源文件真实行号对齐此时行号起始值由内容过滤器自动计算见下文。linenos.rst 是这三者的经典组合示例.. literalinclude:: literal.inc :language: python :lineno-start: 200 .. literalinclude:: literal.inc :language: python :lines: 5-9 :lineno-match::lines: 5-9只取源文件第 5 至 9 行:lineno-match:让这些行保持 5–9 的原始编号。HTML 断言验证了第 5 行显示class Foo:且行号为5tests/test_directives/test_directive_code.py。empty.inc空文件配合:lineno-match:的场景同样被测试覆盖。内容过滤器管线literalinclude 的底层实现与直觉不同literalinclude并不直接读取文件后原样输出而是经过一条过滤器管线sphinx/directives/code.pyfilters [ self.pyobject_filter, self.start_filter, self.end_filter, self.lines_filter, self.dedent_filter, self.prepend_filter, self.append_filter, ] lines self.read_file(self.filename, locationlocation) for func in filters: lines func(lines, locationlocation)每个过滤器对应一组选项按固定顺序执行。这意味着你可以在一次包含中组合多个选项先按pyobject定位对象、再按start/end标记裁剪、再用lines精确取行、最后dedent/prepend/append整形。测试 tests/test_directives/test_directive_code.py 验证了lines start-after end-before三者的组合结果。文本标记截取start_filter/end_filtersphinx/directives/code.py通过查找字符串子串定位边界:start-after: Foo从匹配行之后开始不包含该行:start-at: Foo从匹配行本身开始包含该行:end-before: Bar在匹配行之前结束不包含该行:end-at: Bar在匹配行本身结束包含该行。行号规格截取lines_filtersphinx/directives/code.py与code-block的emphasize-lines共用parse_line_num_spec解析器支持5-9、1,3,5、2-、-5等写法若取出的行集合不连续却又要配合:lineno-match:会抛出Cannot use lineno-match with a disjoint set of lines错误。Python 对象提取pyobject_filtersphinx/directives/code.py利用 Sphinx 的 Python 源码分析器ModuleAnalyzersphinx/pycode/init.py定位class Foo或Foo.bar的起止行从而只包含对象定义本身含装饰器见 py-decorators.inc 与对应测试 tests/test_directives/test_directive_code.py。例如对 literal.inc 提取Bar.baz得到的是缩进的def baz()方法体。互斥选项与错误处理LiteralIncludeReader.INVALID_OPTIONS_PAIRsphinx/directives/code.py列出了禁止同时使用的选项组合如lineno-match不能与lineno-start、prepend、append共用否则行号与源文件无法对齐start-after与start-at、end-before与end-at各自互斥diff不能与pyobject、lineno-start、lineno-match、lines及任何 start/end 标记同时使用。违反互斥会抛出ValueError最终被 sphinx/directives/code.py 捕获并转为文档级 warning不会中断构建——这正是literalinclude与 docutils 原生.. include::的差异之一文件缺失时只警告、不报错。编码、制表符与依赖追踪:encoding:覆盖默认读取编码config.source_encoding编码错误会提示“try giving an :encoding: option”sphinx/directives/code.py:tab-width: N在读取时通过expandtabs(N)展开制表符sphinx/directives/code.py配合pyobject可精确提取缩进正确的对象体tests/test_directives/test_directive_code.pynote_dependency()sphinx/directives/code.py会将被包含文件登记为文档依赖源文件一旦变化Sphinx 增量构建会自动重建相关页面这正是“单一事实来源”能落地的机制保障。深入测试工程如何亲自验证与复现整个test-directive-code根目录本身就是一份可运行的迷你 Sphinx 工程配有自己的 tests/roots/test-directive-code/conf.py仅设置exclude_patterns与numfig True。你可以用 Sphinx 直接构建它观察每种选项的渲染效果# 在仓库根目录下构建测试根文档 python -m sphinx -b html tests/roots/test-directive-code /tmp/test-directive-code-out构建产物中index.html对应 index.rst 的code-block与literalinclude基础示例linenos.html、emphasize.html、caption.html、dedent.html分别对应各专项用例。若需按行核对输出节点可改用 XML 构建器python -m sphinx -b xml tests/roots/test-directive-code /tmp/test-directive-code-xml随后打开index.xml即可看到literal_block节点的language、linenos、classes、names等属性以及真实文本内容与 tests/test_directives/test_directive_code.py 中基于etree_parse的断言一一对应。小结从测试用例到生产文档的最佳实践代码与文档解耦能用literalinclude就不要手抄代码借助pyobject、start/end标记与lines精确裁剪配合:lineno-match:保持行号真实杜绝文档与源码的同步漂移合理使用行号短代码块优先:emphasize-lines:聚焦重点长代码块用:linenos:或highlight指令的:linenothreshold:按行数阈值自动启用行号善用标题与命名开启numfig后:caption:让代码块获得Listing N编号:name:使其成为可交叉引用的目标理解选项边界牢记lineno-match与prepend/append、diff与行类选项之间的互斥关系避免写出无法构建的组合追踪依赖保证增量构建literalinclude的文件依赖登记机制意味着被包含源码的任何改动都会自动触发重新构建这是大型文档项目保持输出新鲜的隐形保障。如果希望进一步探索官方使用指南见 doc/usage/restructuredtext/directives.rst指令实现源码见 sphinx/directives/code.py完整测试集见 tests/test_directives/test_directive_code.py 与 tests/roots/test-directive-code。赞分享文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载相关推荐Slidev 代码块行高亮实战{行号|阶段} 语法解析、点击动画联动与源码实现Slidev 代码块行高亮实战 {行号|阶段} 语法解析、点击动画联动与源码实现 本文讲解 Slidev 中代码块的“行高亮”Line Highlighti前端开发工具3步实现ReactQuill代码块高级编辑语法高亮与行号显示全攻略3步实现ReactQuill代码块高级编辑语法高亮与行号显示全攻略 你是否还在为富文本编辑器中代码块显示混乱而烦恼开发博客、技术文档或在线教育平台时如何让前端UI组件VuePress 代码片段导入与多行高亮实战深入解析 /file{1-3} 语法及源码实现VuePress 代码片段导入与多行高亮实战深入解析 /file{1 3} 语法及源码实现 导读 VuePress 内置的 Markdown 扩展支前端文档SSR上一篇pyLDAvis完整教程从零开始把LDA主题模型变成交互式可视化仪表盘下一篇iFakeLocation三步在iPhone上模拟虚拟定位的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考