文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载Sphinx 4.5.0 于 2022 年 3 月 28 日发布本指南基于仓库内官方变更日志 doc/changes/4.5.rst 展开逐条解读该版本的不兼容变更、新增配置项与缺陷修复并结合当前仓库源码sphinx/ext/extlinks.py、sphinx/builders/html/__init__.py、sphinx/_cli/util/colour.py等讲解各功能背后的实现原理与落地用法。读完本文你将掌握 extlinks 硬编码链接检测的开启方式、HTML 搜索摘要与快捷键的配置方法、终端强制/禁用配色的环境变量约定以及 i18n 翻译告警的抑制技巧。一、版本概览项目内容版本号4.5.0发布日期2022-03-28不兼容变更2 项弃用项1 项新增特性9 项缺陷修复15 项该版本的主要技术方向可以概括为三点让外部链接extlinks的硬编码检测更可控、提升 HTML 搜索与主题交互体验、改善多语言i18n与 C 域domain的细节能力。二、不兼容变更Incompatible changes1. extlinks硬编码链接检测器默认关闭#10112extlinks扩展用于在 reST 文档中通过别名角色如:exmpl:链接统一管理外部 URL避免硬编码。Sphinx 4.5 中引入的硬编码链接检测器hardcoded links detector默认处于关闭状态此前版本中该检测行为会直接生效可能给既有项目带来非预期告警4.5 起默认False需要显式开启详见下文新增特性部分。从源码看sphinx/ext/extlinks.py 中的ExternalLinksChecker后置变换post-transform在run()入口首先检查配置开关def run(self, **kwargs: Any) - None: if not self.config.extlinks_detect_hardcoded_links: return for refnode in self.document.findall(nodes.reference): self.check_uri(refnode)即当配置项未开启时变换直接返回不会扫描文档中的reference节点因此存量文档不会突然出现大量告警这是该变更属于不兼容但方向为放宽的原因。2. std 域禁止通过:ref:引用内联目标#9993, #10177标准域std中的:ref:角色此前允许引用内联目标inline targetSphinx 4.5 开始不再允许这种用法。:ref:的正确用法是引用显式定义的标签label例如.. _my-label: 内容…… 详见 :ref:my-label。而内联目标形如_目标名:出现在行内不属于可通过:ref:稳定解析的引用对象强行引用会解析失败。该变更让跨文档引用的语义更严格避免了歧义目标。三、弃用项Deprecated本版本仅弃用一项 APIsphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()Napoleon 扩展用于解析 Google / NumPy 风格的 docstring。_qualify_name()是该解析器内部用于限定类型名称的私有方法属实现细节因此被标记弃用后续版本将移除。对使用napoleon扩展的普通用户而言该弃用不影响配置与文档编写只有深度定制 docstring 解析器的用户才需要留意。四、新增特性Features added1. 终端配色支持FORCE_COLOR与NO_COLOR环境变量#10260Sphinx 4.5 的终端彩色输出遵循社区通行的NO_COLOR/FORCE_COLOR约定设置NO_COLOR或兼容拼写NO_COLOUR强制禁用颜色输出设置FORCE_COLOR或FORCE_COLOUR强制启用颜色输出即使输出不是 TTY例如在管道、重定向或 CI 场景下。对应实现位于 sphinx/_cli/util/colour.py 的terminal_supports_colour()if NO_COLOUR in _environ or NO_COLOR in _environ: return False if sys.platform win32: return True if FORCE_COLOUR in _environ or FORCE_COLOR in _environ: return True if _environ.get(CI, ).lower() in {true, 1}: return True从源码可以推断出其判定优先级NO_COLOR优先于FORCE_COLOR先检查前者随后依次考虑 Windows 平台、强制开启、CI 环境变量、stdout是否为 TTY以及TERM是否为 dumb/unknown。实际使用示例# 在 CI 中强制输出彩色日志 FORCE_COLOR1 sphinx-build -b html source/ build/ # 在管道处理时禁用颜色 NO_COLOR1 sphinx-build -b html source/ build/ | tee build.log2. autosummary摘要表格新增autosummaryCSS 类#10234autosummary扩展生成的汇总表此前仅使用longtable类4.5 起同时添加autosummaryCSS 类便于主题与自定义样式精准定位这些表格。实现见 sphinx/ext/autosummary/init.py, classes[autosummary, longtable, *self.options.get(class, ())]由此文档站维护者可以在自定义 CSS 中直接写table.autosummary { border-collapse: collapse; }而不必担心影响普通表格的样式。3. extlinks带标题的硬编码链接给出更贴切的替换建议#10125硬编码链接检测器在发出替换建议时会区分链接文本与 URL 是否一致。若 reST 中写作Foo https://example.com/foo_链接文字与地址不同建议消息会生成带显式标题的替换写法:alias:\Foo 若两者相同则生成:alias:foo。对应逻辑在 sphinx/ext/extlinks.pyif uri ! title: replacement f:{alias}:{rst.escape(title)} {value} else: replacement f:{alias}:{value}4. extlinks新增extlinks_detect_hardcoded_links配置项#10112这是与前述不兼容变更配套的新增能力。在conf.py中开启后构建器会对每个外部链接reference节点且无internal标记检查它是否可用某个已定义的 extlinks 别名替换若命中则输出告警并给出替换建议extlinks { issue: (https://github.com/sphinx-doc/sphinx/issues/%s, #%s), } extlinks_detect_hardcoded_links True # 默认 False开启后若文档中出现硬编码的#12345 https://github.com/sphinx-doc/sphinx/issues/12345_构建时会收到类似hardcoded link … could be replaced by an extlink (try using :issue:12345 instead)的提示。其配置定义与开关检查分别在 sphinx/ext/extlinks.py 与 sphinx/ext/extlinks.pyapp.add_config_value( extlinks_detect_hardcoded_links, False, env, typesfrozenset({bool}) )需要注意的匹配细节见check_uri()检测时用re.escape(base_uri)转义后再把%s替换为(?Pvalue.)进行匹配并且要求捕获的value中不含斜杠即只对单层路径式的替换给出建议避免把深层 URL 误报成可替换链接。5. HTML 搜索新增html_show_search_summary配置项#9494, #9456此前 HTML 搜索结果页总是显示每条结果下的摘要片段4.5 起可通过配置关闭摘要适合追求极致简洁或性能的场景html_show_search_summary False # 默认 True该配置由 HTML 构建器注入全局上下文见 sphinx/builders/html/init.pyshow_search_summary: self.config.html_show_search_summary,配置声明在 sphinx/builders/html/init.pyhtml_show_search_summary, True, html, typesfrozenset({bool})6. HTML 主题新增enable_search_shortcuts快捷键开关#9337基本主题basic新增主题选项enable_search_shortcuts默认开启按/键立即聚焦搜索框Quick search 快捷键按Esc键移除搜索结果的高亮标记。主题选项定义在 sphinx/themes/basic/theme.tomlenable_search_shortcuts True并在 sphinx/themes/basic/static/documentation_options.js.jinja 中序列化到前端ENABLE_SEARCH_SHORTCUTS: {{ true if theme_enable_search_shortcuts|tobool else false}},继承 basic 主题的项目如需关闭可在html_theme_options中设置html_theme_options { enable_search_shortcuts: False, }7. i18n翻译消息尾部添加#noqa可抑制翻译告警#10107多语言构建gettext / i18n过程中若翻译后的文本导致引用键reference keys与原文不一致Sphinx 会输出告警。4.5 起允许在翻译消息msgstr末尾添加#noqa注释显式抑制此类告警便于团队对明知故犯的翻译差异做标记。解析实现在 sphinx/transforms/i18n.pydef parse_noqa(source: str) - tuple[str, bool]: m match(r(.*)(?!\\)#\s*noqa\s*$, source, DOTALL)其中正则使用了反向断言(?!\\)意味着字面反斜杠转义的\#noqa不会被当作抑制标记。具体抑制逻辑见 sphinx/transforms/i18n.py当self.noqa为真且新旧引用键不同old_ref_keys ! new_ref_keys时跳过告警。注意事项literal block字面块内无法使用该技巧因为块内内容不会被转义块外如需字面含义可写作\#noqa参见 sphinx/transforms/i18n.py 中的注释说明。以zh_CN的 PO 文件为例其翻译条目位于仓库 sphinx/locale/zh_CN 目录同时包含.po、.mo与前端.js语言数据。8. C 域支持类、联合体与枚举上的属性#10252cpp域在 4.5 起支持在类class、联合体union与枚举enum声明上书写属性例如.. cpp:class:: [[deprecated]] MyClass对应的解析与 AST 支持位于 C 域实现目录 sphinx/domains/cpp。这使 Sphinx 生成的 C API 文档能更忠实地反映现代 C 代码中的属性标注如[[deprecated]]、[[nodiscard]]等供cpp:class:、cpp:union:、cpp:enum:等指令使用。9.:pep:角色改用peps.python.org生成 URL#10253标准域中的:pep:角色此前生成指向www.python.org/dev/peps/的链接4.5 起改为指向官方新域名https://peps.python.org/。该基础 URL 配置在 sphinx/environment/init.pypep_base_url: https://peps.python.org/,这意味着文档中形如:pep:20 的引用会自动链接到https://peps.python.org/pep-0020/。仓库内其他源码文档如 sphinx/ext/doctest.py 中的版本规范引用也已同步使用该域名。五、缺陷修复Bugs fixedautodoc 相关#9876无法为由原生二进制模块构造并导入的类生成文档。修复后 autodoc 对来自 native 扩展的类对象如通过 C 扩展动态创建的类也能正确解析其文档字符串。#10133mock 模块被用于类型注解时崩溃。该场景常见于autodoc_mock_imports配置的项目修复避免了在类型注解解析阶段访问 mock 属性引发的异常。#10146autodoc_default_options不支持无值选项no-value option。修复后可在默认选项中书写如autodoc_default_options {members: True}之类的无参数开关。#9971目标对象被不可哈希对象注解时抛出TypeError。修复使 autodoc 能容忍不可哈希的类型注解对象。extlinks / 搜索 / LaTeX / manpage / i18n 相关#10205硬编码链接检测在编译正则时失败。修复了re.escape与%s替换组合时对特殊字符如%处理不当导致的re.error。#10277HTML 搜索无法搜索短单词如 use。修复了分词或最小词长判断对短查询词的误拦截使两三个字母的关键词也能正常命中。#9529LaTeX 中具名自动编号脚注如[#named]被多次引用时渲染成问号。修复后多个引用点均能正确解析为脚注编号。#9924LaTeXlatexpdf中多行cpp:function指令产生过大的垂直间距。#10158自 4.4.0 起未文档化的变量/结构体成员在 LaTeX 输出中出现过多空白。#10175同一脚注名在不同文档中复用导致 LaTeX 命名脚注引用指向错误脚注。#10269manpage 构建器无法解析:ref:交叉引用的标题。#10179抑制 rST localization 警告。#10118imgconverter 对远程 URI 进行了不必要的可用性检查应仅对本地图片做转换工具探测。#10181napoleon 在启用napoleon_use_ivar时Google 风格 docstring 的属性被显示为类属性。#10122make.bat在显示帮助前不检查sphinx-build命令是否安装修复后给出更友好的提示。六、升级建议存量 extlinks 用户若此前依赖检测器自动告警请在升级后于conf.py显式设置extlinks_detect_hardcoded_links True以恢复行为首次开启建议在 CI 环境观察告警数量再逐步整改硬编码链接。多语言团队若存在有意不一致的翻译条目例如译文中改变了引用文本可在 msgstr 尾部添加#noqa抑制告警同时保留\#noqa作为字面转义手段。HTML 主题定制者enable_search_shortcuts默认开启若与页面既有键盘交互冲突可在html_theme_options中关闭/与Esc的行为由 basic 主题的documentation_options.js控制。API 使用者sphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()已弃用请避免在自定义扩展中依赖该方法。完整变更清单可继续查阅仓库内的 doc/changes/index.rst 及各版本记录如 doc/changes/4.4.rst、doc/changes/5.0.rst以了解该版本在 Sphinx 版本演进中的位置。赞分享文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载相关推荐Actual 23.11.0 版本解析移动端预算编辑、Web 同步快捷键与稳定性增强Actual 23.11.0 版本解析移动端预算编辑、Web 同步快捷键与稳定性增强 本篇技术指南以 Actual 2023 年 11 月发布的 23.11.金融科技本地优先PWASphinx 3.1 版本特性深度解析autodoc/autosummary 增强、C/C 命名空间与 HTML 主题改进Sphinx 3.1 版本特性深度解析autodoc/autosummary 增强、C/C 命名空间与 HTML 主题改进 Sphinx 3.1 系列2文档开发工具WVP-GB28181快速上手指南一条命令把多品牌摄像头接进同一个管理页WVP GB28181快速上手指南一条命令把多品牌摄像头接进同一个管理页 WVP GB28181 pro下称 WVP是基于 GB28181 2016、部标后端音视频前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考