Sphinx 2.0 升级指南：HTML5 默认输出、master_doc 变更与弃用 API 全景解析

文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载Sphinx 2.0 是 Sphinx 文档生成器本项目仓库 README.rst 所对应的开源项目从 Python 2 时代迈向 Python 3 时代的关键大版本它正式放弃 Python 2.7 与 Docutils 0.11将 HTML 输出默认切换为 HTML5把master_doc的默认值从contents改为index并拆分了多个 sphinxcontrib 子包。本文以仓库内的官方变更记录 doc/changes/2.0.rst 为骨架结合当前仓库源码如 sphinx/config.py、sphinx/builders/html/init.py进行印证完整梳理 2.0 的依赖变化、不兼容变更、弃用 API、新增特性与修复清单帮助从 1.x 升级的开发者系统化评估迁移工作。一、Sphinx 2.0 版本概览Sphinx 2.0 系列包含两个正式发布版变更记录见 doc/changes/2.0.rst2.0.02019-03-29 发布承载全部核心变更含 2.0.0b1、2.0.0b2 两个里程碑2.0.12019-04-08 发布修复性补丁主要解决 LaTeX 系统标签翻译、弃用警告未触发sphinx.application.CONFIG_FILENAME、sphinx.builders.htmlhelp、viewcode_import、napoleon 扩展对含引用的 raised 段抛出AttributeError#6220、#6225、HTML5Translator 处理非法 field 节点崩溃#6263、第三方主题下搜索功能失效#6244等问题。2.0 的整体脉络可以概括为三条主线收紧运行时依赖Python/Docutils/TeX Live 版本门槛、清理历史包袱大量 1.7.x 时代弃用特性的移除与 API 折旧、默认行为切换HTML5、master_doc、LaTeX 字体策略。二、依赖与运行环境变化升级前必读2.0.0b1 对运行时依赖做了系统性收紧升级前应先核对构建环境依赖项2.0 要求说明Python不再支持 2.7 / 3.4只支持 Python 3.5Docutils不再支持 0.11移除 Docutils 0.11 支持TeX LiveLaTeX 构建器要求TeX Live 2015 或以上低于此版本将无法正常构建 PDFrequests2.5.0 或以上Sphinx 自身 HTTP 请求基础库six不再是依赖代码库已完全切换到 Python 3 语法sphinxcontrib-websupport不再是依赖websupport 从核心剥离需单独安装使用同时原内置于 Sphinx 核心的多个构建器被拆分为独立的 sphinxcontrib 子包sphinxcontrib.applehelpsphinxcontrib.devhelpsphinxcontrib.htmlhelpsphinxcontrib.jsmathsphinxcontrib.serializinghtmlsphinxcontrib.qthelp若项目在conf.py的extensions中直接引用了上述构建器扩展升级后需改为安装对应子包再引用。LaTeX 构建的字体与系统包要求LaTeX 相关依赖变化最为具体主要围绕 Unicode 希腊字母与字体策略使用pdflatex作为latex_engine时正文非数学环境中的 Unicode 希腊字母改为通过文本字体渲染不再转义为数学标记按 doc/latex.rst 中latex_elements的fontenc键配置追加LGR编码可启用该支持此时例如 Ubuntu xenial 需要额外安装texlive-lang-greek和若未修改默认字体配置cm-super(-minimal)包。latex_engine设为xelatex或lualatex时默认改用FreeFontOpenType 字体Ubuntu xenial 下由fonts-freefont-otf提供Fedora 29 下由texlive-gnu-freefont提供。三、不兼容变更全景迁移核心1.master_doc默认值改为index2.0 将master_doc主文档默认值从contents改为index这与sphinx-quickstart长期以来生成的默认值保持一致。从 1.x 升级且未显式设置master_doc的项目若根目录下既有index.rst又有contents.rst构建行为将发生变化。这一点在当前仓库源码中仍留有明确痕迹sphinx/config.py 中master_doc: _Opt(index, ...)的默认值即index且check_master_doc()sphinx/config.py会在检测到master_doc index但项目中没有index文档、只有contents时打印警告并回退def check_master_doc(app, env, added, changed, removed): Sphinx 2.0 changed the default from contents to index. docnames app.project.docnames if ( app.config.master_doc index and index not in docnames and contents in docnames ): logger.warning( __(Sphinx now uses index as the master document by default. To keep pre-2.0 behaviour, set master_doc \contents\.) ) app.config.master_doc contents可见官方为老项目保留了兼容回退路径在conf.py中显式设置master_doc contents即可维持 1.x 行为。2. HTML 输出默认切换为 HTML52.0 默认输出 HTML5#4587并通过新增的html4_writer配置项默认False提供回退到旧 HTML4 写器的途径。换言之# conf.py —— 仅 2.0 时代需要用于保留旧输出 html4_writer True有趣的是从当前仓库源码看HTML4 写器的生命周期已经终结在 sphinx/builders/html/init.py 中error_on_html_4()会在检测到html4_writerTrue时直接抛出ConfigErrorHTML 4 is no longer supported by Sphinx。因此升级到现代 Sphinx 版本时HTML4 相关的兼容性配置已完全失效应直接迁移到 HTML5 输出并检查自定义模板的 HTML 兼容性。3. LaTeX 行为变更2.0 的 LaTeX 变更点较多逐条说明消息资源移至sphinxmessage.sty部分标签不再使用\captionslang宏xelatex/lualatex默认改用 FreeFont OpenType 字体refs: #5645xelatex/lualatex的代码块字号改用\small与pdflatex的 Courier 字符宽度对齐refs: #5768若使用其他 OpenType 字体可通过latex_elements的fvset键调整正文希腊字母不再转义为数学标记需在latex_elements的fontenc键中追加LGR编码仅当文档需要时language en时fncychap的章节样式由Sonny改为Bjarne与未指定语言时的行为一致refs: #5772manualdocclass 中硬编码的\lsection/\lsubsection重定义改为在\sphinxtableofcontents时执行意味着自定义 LaTeX preamble 中的同名定义会被覆盖如需插入自定义定义应改用\sphinxtableofcontentshook钩子超大图片的包含会缩放至不超过文本宽度与高度即使显式指定了 width/height 选项refs: #5956。4. 其他行为变更doctest 高亮#5770doctest 块的高亮遵循highlight_language配置默认按 python3 高亮表格/图片对齐#4550所有未指定align选项的表格与图片默认居中显示epub 标题epub_title默认值改为project配置项quickstart 简化生成的conf.py大幅精简部分交互式问题被移除但仍可通过命令行选项指定#4148websupport 解绑从 Sphinx 核心移除请改用sphinxcontrib-websupportC 基类可见性基类访问权限如private现在总是如实渲染不再省略texinfo2.0.0b2图片文件复制到name-figure目录翻译器构造参数HTMLTranslator、HTML5Translator、ManualPageTranslator的参数顺序发生变化第三方子类需同步调整。四、弃用 API 清单与替代方案2.0.0b1 对 1.7.x 时代遗留的一大批 API 发出RemovedInSphinx30Warning部分在 2.0.1 中被标记为 pending。按模块归纳如下配置项html_experimental_html5_writerHTML5 已成为默认无需再配置autodocDocumenter.get_doc()、DocstringSignatureMixin.get_doc()、ClassDocumenter.get_doc()的encoding参数importer._MockModule的importer参数importer._MockImporter环境 APIenv.doc2path()的suffix参数与字符串风格base参数sphinx.io.SphinxBaseFileInput、SphinxFileInput.supported、SphinxRSTFileInputbuildersphinx.builders.epub3.Epub3Builder.validate_config_value()、sphinx.builders.html.SingleFileHTMLBuilder、sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()搜索sphinx.search.WordCollector.is_meta_keywords()的nodetype参数rolesabbr_role()、emph_literal_role()、menusel_role()、index_role()、indexmarkup_role()sphinx.addnodes.abbreviationutil 模块sphinx.util.attrdict、force_decode()、get_matching_docs()、jsonimpl、osutil.walk()、PeekableIterator、pycompat系列NoneType、TextIOWrapper、UnicodeMixin、htmlescape、indent、sys_encoding、terminal_safe()、u等LaTeX/texinfo/text 翻译器writers.latex.ExtBabel、LaTeXTranslator._make_visit_admonition()、babel_defmacro()、collect_footnotes()、generate_numfig_format()、TexinfoTranslator._make_visit_admonition()、TextTranslator._make_depart_admonition()LaTeX 模板变量logo、numfig_format、pageautorefname、translatablestrings其他sphinx.config.check_unicode()、string_classes、sphinx.cmd.quickstart.term_decode()、TERM_ENCODING、sphinx.testing.util.remove_unicode_literal()、IndexBuilder.feed()省略filename的兼容回退、autosummary.Autosummary.warn()/genopt/warnings/result、doctest.doctest_encode()、registry.SphinxComponentRegistry.add_source_input()等。完整清单与替代 API 可查阅 doc/extdev/deprecated.rst 的弃用 API 列表文档中通过:ref:deprecation APIs list 指引。五、新增特性详解1. 搜索结果预览渲染为 HTML#1618生成 HTML 文档的搜索结果显示从展示原始 reStructuredText 标记改为渲染对应 HTML可读性大幅提升第三方扩展sphinx-pretty-searchresults因此不再必要。注意自定义或第三方 HTML 模板若改写了搜索函数可能会覆盖这一改进。配套改进#6016搜索摘要增加占位符防止搜索结果链接在搜索结束时因布局变化而位移便于用户定位点击。2. autodoc 增强autodoc_default_options支持member-order选项#5533可为automodule/autoclass等指令统一设置成员排序策略alphabetic/bysource/groupwiseautodoc_default_options接受True作为布尔值#5459例如autodoc_default_options {members: True}不再需要字符串形式的Trueautodoc 支持suppress_warnings配置#4182可定向屏蔽 autodoc 相关告警新增autodecorator指令#1148用于为装饰器生成文档mock 对象的类型注解现在显示可读名称#5394。相关源码见 sphinx/ext/autodoc/init.pyautodoc_default_options的注册与 sphinx/ext/autodoc/_directive_options.pymember-order选项定义。3. autosummaryautosummary_mock_imports新增autosummary_mock_imports配置#5635在导入被摘要的目标模块时 mock 外部库避免生成摘要时因缺失第三方依赖而失败。源码中该配置的注册见 sphinx/ext/autosummary/init.py其默认值继承autodoc_mock_imports。4. sphinx-apidoc--extensions选项sphinx-apidoc新增--extensions命令行选项#5841在--full模式下可启用任意扩展同时提供--ext-autodoc、--ext-viewcode等便捷子选项。参数解析实现见 sphinx/ext/apidoc/_cli.py。5. C 域增强新增cpp:alias指令#4981插入引用既有声明的声明列表适用于制作概要/synopsis新增cpp:struct指令与cpp:class互补修复cpp:alias在 LaTeX及 singlehtml构建下的问题#5946。6. HTML 搜索匹配规则改进搜索时包含长度 ≥ 3 的搜索词的单词即视为命中#1341同时修复了多关键词搜索时某一关键词短于 3 字符导致结果为空的问题2.0.0b1 修复清单。此外searchindex.js改为延迟加载defer而非 ajax 方式#3620。7. 版本指令专用 CSS 类#5660versionadded、versionchanged、deprecated指令现在除通用versionmodified类外还会生成各自的专用 CSS 类added、changed、deprecated方便主题做差异化样式。8. autosectionlabelautosectionlabel_maxdepth新增autosectionlabel_maxdepth配置#4261限制自动注册标签的章节深度避免深层小节标题污染标签命名空间。当前源码 sphinx/ext/autosectionlabel.py 中通过get_node_depth()计算章节深度并在深度达到上限时跳过注册def register_sections_as_label(app, document): domain app.env.domains.standard_domain for node in document.findall(nodes.section): if ( app.config.autosectionlabel_maxdepth and get_node_depth(node) app.config.autosectionlabel_maxdepth ): continue ...9. code-block 指令参数可省略#1851code-block指令允许省略语言参数此时跟随最近的highlight指令或highlight_language配置与code指令行为一致后者在 2.0.0b2 中也得到支持见 #2155。10. 其他新增特性htmlhelp新增htmlhelp_file_suffix与htmlhelp_link_suffix配置#4018text 构建器支持复杂表格colspan/rowspan#5559LaTeX支持在非西里尔文文档中渲染希腊文与西里尔文 Unicode 字符pdflatex引擎也可用refs: #5645linkcheck同时校验远程图片是否存在#5196githubpages设置html_baseurl时自动为自定义域名创建 CNAME 文件#5924epub对重复的 ToC 条目输出警告#4611。六、修复的典型缺陷按构建器归纳2.0 各里程碑修复清单可归纳为以下几类LaTeX希腊 Unicode 不应被翻译而应使用 textgreek 包#1682俄语 xelatex/lualatex默认字体配置下 PDF 构建失败#5247章节标题中的希腊字母在 PDF 书签中消失#5248数学指令中的 Unicode 希腊字母破坏 PDF 构建#5249需按latex_elements的textgreek键与latex_engine设置处理lualatex 下的转义不足以阻止 TeX ligature#5179省略latex_documents时项目名与作者不显示HTMLglossary 一词多义描述时生成非法 HTML5refs: #46112.0.0b2 中 anchor 链接未加到图片#6096、表格单元格与列表项边距过大#6113、highlight指令的linenothreshold选项被忽略#5508HTML 搜索多关键词且含 3 字符词时搜索恒返回空texinfomake install-info语法错误、macOS 失败#3079 相关、图片未复制#3079C 域完整 xref 恰以短 xref 为前缀时的解析#62082.0.1 修复、花括号初始化器解析、旧式索引节点AttributeError#6172其他QtHelp 的 .qhp 文件使用平台相关路径分隔符交叉引用位于标题中被渲染为字面量#5391citation_reference节点的 classes 属性丢失#6147i18n 下隐藏 ToC 的标题翻译缺失#6178inheritance_diagram的parts选项文档化并允许负值#4872py 域生成意外前缀#61962.0.0 final 修复。七、测试基础设施变化不再使用SPHINX_TEST_TEMPDIR环境变量2.0.0b1新增测试辅助函数sphinx.testing.restructuredtext.parse()2.0.0b2对应实现位于 sphinx/testing/restructuredtext.py用于在测试中快速将 reStructuredText 解析为 docutils 节点树。八、升级检查清单综合全文从 1.x 升级到 2.0 时建议按以下清单逐项核对运行环境确认 Python ≥ 3.5、Docutils 0.11、requests ≥ 2.5.0LaTeX 构建确认 TeX Live ≥ 2015并按需安装希腊语/FreeFont 字体包参照 doc/usage/installation.rst 与 doc/latex.rstconf.py显式设置master_doc推荐index或保留contents以维持旧行为移除html_experimental_html5_writer如需旧输出临时设置html4_writer True注意该配置在后续版本已彻底移除详见 sphinx/builders/html/init.py扩展列表将拆分的 sphinxcontrib 子包htmlhelp、serializinghtml 等与 websupport 改为独立安装后引用自定义翻译器/模板核对HTMLTranslator等构造参数顺序、LaTeX 模板变量logo、numfig_format等与搜索模板的改动弃用 API逐项清理 doc/extdev/deprecated.rst 清单中的调用点重点检查env.doc2path()、autodocget_doc()、sphinx.util.pycompat等高频接口输出差异回归检查表格/图片居中显示#4550、doctest 高亮策略、C 基类可见性渲染、texinfo 图片目录等默认行为变化对现有文档的影响。Sphinx 2.0 为后续版本奠定了Python 3-only HTML5 默认的基线理解本版本的迁移语义是维护与升级任何基于 Sphinx 构建的文档项目的前提。赞分享文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载相关推荐Sphinx 8.0 升级迁移指南破坏性变更、废弃 API 移除与配置默认值调整全解析Sphinx 8.0 升级迁移指南破坏性变更、废弃 API 移除与配置默认值调整全解析 Sphinx 8.0 系列8.0.0 于 2024 07 29 发布文档开发工具Vector Lua 变换 search_dirs 默认值变更详解默认解析配置目录与升级指南Vector Lua 变换 search_dirs 默认值变更详解默认解析配置目录与升级指南 本指南围绕 Vector 0.9.0 引入的一项 breakin可观测性数据工程数据集成日志分析ESP-IDF 6.0 存储与 VFS 迁移指南破坏性变更、弃用 API 与新默认配置ESP IDF 6.0 存储与 VFS 迁移指南破坏性变更、弃用 API 与新默认配置 导读 本文基于 ESP IDF 官方迁移指南 docs/en/migr物联网嵌入式创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考