文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载Sphinx 5.1含补丁版本 5.1.0 与 5.1.1于 2022 年 7 月发布是 5.x 系列中承上启下的一个重要版本。本指南以仓库中的官方变更日志 doc/changes/5.1.rst 为骨架系统讲解该版本引入的include_patterns配置、option_emphasise_placeholders选项、HTML/LaTeX 主题增强、Docutils 0.19 兼容性等核心变更并结合sphinx/config.py、sphinx/project.py、sphinx/domains/std/__init__.py等源码与官方文档 doc/usage/configuration.rst、doc/latex.rst 进行源码级佐证。读完本文你将掌握 5.1 版本的全部新特性、已知问题修复清单及其底层实现原理能够据此评估升级路径并配置新选项。版本概览版本发布日期定位5.1.02022-07-24引入主要新特性include_patterns、option_emphasise_placeholders、LaTeX 盒子样式扩展、Docutils 0.19 支持5.1.12022-07-26修复 5.1.0 引入的两个回归问题napoleon 迭代器 ValueError、第三方 builder 兼容性5.1.1 作为紧随 5.1.0 两日后发布的补丁版本修复了 5.1.0 引入的回归问题建议所有 5.1.0 用户在升级时直接使用 5.1.1。新特性详解1. 支持 Docutils 0.19#106565.1.0 起 Sphinx 官方支持 Docutils 0.192022-07-05 发布。这意味着构建环境可以将docutils依赖升级到 0.19 而不会破坏 Sphinx 构建流程。需要特别注意的是5.1.0 的 HTML 主题在 Docutils 0.18 早期版本非 0.18.1下存在构建失败问题详见下文Bug 修复章节的 #10596原因是 Docutils 0.18 缺少Node.findall()方法。因此若停留在 Docutils 0.18 系列应至少使用 0.18.1。2. 新增include_patterns配置项#10518include_patterns是exclude_patterns的对偶配置用于正向指定需要纳入构建的源文件。# conf.py include_patterns [**] # 默认值递归包含源目录下所有文件 include_patterns [library/xml] # 仅包含 library/xml 目录 include_patterns [**/doc] # 包含所有 doc 目录文档与源码共存时很有用优先级规则exclude_patterns的优先级高于include_patterns见 doc/usage/configuration.rst。也就是说被exclude_patterns排除的文件即使匹配include_patterns也不会被纳入。源码级原理配置注册于 sphinx/config.pyinclude_patterns: _Opt([**], env, frozenset((str,)))默认值为[**]类型为字符串序列属于环境级env配置。文件发现流程BuildEnvironment.find_files()在 sphinx/environment/init.py 中将exclude_patterns templates_path builder.get_asset_paths()作为排除路径将include_patterns作为包含模式一并传给Project.discover()。Project.discover()sphinx/project.py调用get_matching_files(srcdir, include_paths, [*exclude_paths, *EXCLUDE_PATHS])完成 glob 匹配其中EXCLUDE_PATHS是 Sphinx 内置的默认排除项如.git等。匹配规则与exclude_patterns一致模式针对相对于源目录的路径进行匹配所有平台统一使用斜杠作为目录分隔符。这一配置尤其适合文档与源码混放的仓库可以精确圈定文档范围避免把无关的.rst/.md文件卷入构建。3. 新增option_emphasise_placeholders配置项#10366该选项用于在option指令std 域的命令行选项描述中强调占位符。# conf.py option_emphasise_placeholders True.. option:: -foption{TYPE} 如上配置下TYPE 会被强调渲染要显示字面量花括号需用反斜杠转义\{。官方文档doc/usage/configuration.rst给出的示例option_emphasise_placeholdersTrue且.. option:: -foption{TYPE}时TYPE会被强调显示。该选项类型为bool默认False在 sphinx/config.py 注册为option_emphasise_placeholders: _Opt(False, env, frozenset((bool,)))。源码级原理该选项在Cmdoption.handle_signature()sphinx/domains/std/init.py中生效选项签名按,分隔成多个潜在选项逐个用option_desc_re正则校验当option_emphasise_placeholders开启时多个选项之间使用desc_sig_punctuation(,)与desc_sig_space分隔而非默认的desc_addname(, )参数部分会被samp_role.parse()解析[/]/等作为标点节点其余文本作为强调节点输出{TYPE}中的TYPE因此被强调渲染关闭时参数整体作为desc_addname(args, args)输出保持旧行为。4. HTML 主题stylesheet支持多个 CSS 文件#104445.1 允许通过theme.conf的stylesheet设置指定多个 CSS 文件也允许将html_style设为字符串可迭代对象# conf.py html_style [custom1.css, custom2.css]此前stylesheet只能填单个文件现在可以按顺序加载多个样式表为复杂主题定制提供了便利。5. HTML 主题脚注包裹aside元素#10599使用 Docutils 0.18 或更高版本时连续的脚注会被包裹进aside元素便于独立样式化。该行为与 Docutils 0.19 引入的行为保持一致相当于在 5.1 中提前对齐了 Docutils 0.19 的输出结构。6. LaTeXCSS 风格命名的sphinxsetup键扩展#106485.1 为 LaTeX 输出引入了与 CSS 命名风格类似的sphinxsetup键用于对code-block、topic、attention、caution、danger、error、warning这 7 类指令的盒子分别配置四条独立的border-widthborder-width四个独立的paddingpadding四个corner-radius圆角半径阴影shadow可设为 inset 内阴影边框色、背景色、阴影色border color、background color、shadow color示例配置doc/latex.rstlatex_elements { sphinxsetup: ( pre_border-width2pt, # code-block 边框宽度 pre_border-radius3pt, # code-block 圆角 div.warning_border-width3pt, # warning 指令边框 ... ), }这些键通过latex_elements[sphinxsetup]写入生成的.tex文件也可在文档前导中使用\sphinxsetup{key1value1, key2value2, ...}LaTeX 宏直接设置详见 doc/latex.rst 与 doc/latex.rst。键的详细列表覆盖边框、内边距、圆角、阴影及颜色含additionalcss等。7. LaTeXLatinRules.xdy 中非标准编码的说明#10655LatinRules.xdy见 sphinx/texinputs/LatinRules.xdy中使用的非标准编码在 5.1 中补充了说明文档方便维护者理解 xindy 索引规则的编码约定。8. std 域警告信息使用变量 repr#10439当 std 域显示警告时部分变量改用repr形式输出使空白字符等问题更容易被识别例如不可见的前导/尾随空格会在引号中显现。9. quickstart精简生成的conf.py#10571sphinx-quickstart生成的conf.py模板内容被精简去除了冗余注释减少初始项目的噪音让用户按需自行添加配置。Bug 修复清单HTML 主题#10594使用 Docutils 0.18 时字段名field term后的冒号出现重复。#10596Docutils 版本恰为 0.18而非 0.18.1时因缺少Node.findall()导致构建失败。#10520修复agogo.css_t中 sidebar 类名的使用。#6679修复 agogo 主题中隐藏 toctree 被错误包含的问题。#10566修复enable_search_shortcuts设置不生效的问题。HTML 搜索HTML 标签被当作对象名称的一部分显示——已修复。搜索摘要snippets不应被折叠——已修复。获取搜索摘要时发出次要错误——已修复。搜索结果中显示了头部链接标记——已修复。#10548修复搜索摘要的若干次要问题。Python 域py domain#10550修复反解析各种运算符、-、~、**时出现的多余空白refs: #10551。#9577 / #10088修复同时使用:any:与 autodoc 时重复 Python 引用产生的警告。LaTeX#10506图注figure caption中高亮行内代码角色导致构建错误refs: #10251。#8686code-block 在页面末尾时文本可能溢出并在下一页留下残留物——已修复。#10633用户在 topic 或 admonition 盒子中注入的\color命令可能因上游framed.sty缺陷导致 PDF 颜色泄漏。#10638高亮代码中的彩色盒子如使用 Pygments 样式manni的高亮 diff错误继承了 code-block 边框厚度。#10647desc_signature节点即使有多个节点 ID 也只生成一个\label——已修复。其他#10634使-Ppdb 调试选项在事件触发的异常下工作得更好。#10460日志中节点源码位置始终以绝对路径显示。#10579i18n 在翻译 raw 指令时抛出UnboundLocalError——已修复。5.1.1 补丁版本修复5.1.12022-07-26 发布仅包含两个修复#10701修复新的基于deque的sphinx.ext.napoleon迭代器实现中的ValueError。#10702恢复与第三方 builder 的兼容性。这两项修复直接对应 5.1.0 引入的回归#10467 中 napoleon 迭代器被标记弃用并改用deque实现见下文弃用项以及 5.1.0 对内部接口的调整影响了第三方 builder。升级到 5.1.x 时应使用 5.1.1。弃用项5.1.0 引入两项弃用sphinx.util.stemmer#10467推荐改用snowballstemmer。这意味着基于sphinx.util.stemmer的第三方代码应迁移搜索相关的词干提取逻辑转向snowballstemmer库。sphinx.ext.napoleon.iterators#9856napoleon 扩展的迭代器模块被弃用5.1 内部改用deque实现该实现正是 5.1.1 中 #10701 修复的对象。弃用项会保留一段兼容期但建议在新代码中立即使用替代方案。升级与验证建议升级 Docutils确认 Docutils 版本不低于 0.18.1推荐直接使用 0.19 以享受官方支持。使用 5.1.1 而非 5.1.05.1.1 修复了两个回归问题直接安装Sphinx5.1.1,5.2即可。检查弃用警告构建时留意sphinx.util.stemmer与sphinx.ext.napoleon.iterators的弃用警告及时迁移依赖。验证新增配置若启用include_patterns或option_emphasise_placeholders通过sphinx-build -b html实际构建并检查输出文档树与选项指令渲染效果。第三方 builder 兼容性若项目使用自定义或第三方 builder升级到 5.1.0 后务必测试构建确认不受 #10702 涉及的变化影响5.1.1 已恢复兼容。参考资源官方变更日志doc/changes/5.1.rstinclude_patterns配置说明doc/usage/configuration.rstoption_emphasise_placeholders配置说明doc/usage/configuration.rst配置注册与默认值sphinx/config.py文件发现与 glob 匹配sphinx/environment/init.py、sphinx/project.pyoption指令占位符强调实现sphinx/domains/std/init.pyLaTeXsphinxsetup完整文档doc/latex.rst赞分享文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载相关推荐Sphinx 7.1 版本特性深度解析签名换行、PEP 695 泛型支持与 linkcheck 增强Sphinx 7.1 版本特性深度解析签名换行、PEP 695 泛型支持与 linkcheck 增强 导读 Sphinx 7.1 是 Sphinx 文档生成器文档开发工具IBAnimatable 6.1.0全面解析Swift 5.1支持与100% UIKit兼容性深度评测IBAnimatable 6.1.0全面解析Swift 5.1支持与100% UIKit兼容性深度评测 你还在为iOS动画实现复杂、兼容性差而烦恼IBAni移动开发UI组件Sphinx 4.4 版本特性深度解析autodoc 类型提示、autosummary __all__ 支持与 linkcheck 文档排除实战指南Sphinx 4.4 版本特性深度解析autodoc 类型提示、autosummary __all__ 支持与 linkcheck 文档排除实战指南 导读 本文档开发工具上一篇Skidfuscator社区支持Discord、Wiki和问题解决资源汇总下一篇WeTextProcessing让文本在数字世界与人类语言间自由转换的智能工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考