当前位置：首页 > news >正文

106、【OS】【Nuttx】【周边】文档构建渲染：安装 Sphinx 扩展（下）

news 2025/8/20 14:33:00

【声明】本博客所有内容均为个人业余时间创作，所述技术案例均来自公开开源项目（如Github，Apache基金会），不涉及任何企业机密或未公开技术，如有侵权请联系删除

背景

接之前 blog
【OS】【Nuttx】【周边】文档构建渲染：安装 Sphinx 扩展（上）
【OS】【Nuttx】【周边】文档构建渲染：安装 Sphinx 扩展（中）
分析了 Sphinx 配置文件中的一些扩展文件，如 sphinx_rtd_theme，myst_parser，sphinx.ext.autosectionlabel，sphinx.ext.todo，sphinx_tabs.tabs，sphinx_copybutton 下面继续分析剩下的扩展安装配置

Sphinx 扩展

还是这张图，接着分析剩下的扩展
在这里插入图片描述
其实到这里，已经分析了大部分扩展，只剩下一个 warnings_filter 扩展，这个时候其实屏蔽掉该扩展 Sphinx 也能正常构建渲染了，但是善始善终，下面还是把 warnings_filter 先一起分析了

warnings_filter

首先，从这个扩展的名字可以看出，该扩展不属于 Sphinx 的标准扩展

如果尝试从终端中输入

python3 -m pip install --user warnings_filter --break-system-packages

会发现安装失败，没有这个扩展
在这里插入图片描述
其实这个属于 Nuttx 项目本地扩展，路径在 Documentation/_extensions/warnings_filter.py

ok，那既然是 Nuttx 项目本身自带的扩展，那没啥说的了，扩展都已安装完毕，下面来看下 Esbonio 配置和 Sphinx 构建过程

Esbonio 配置

左下角选择设置，打开设置界面
在这里插入图片描述
在设置搜索框中搜索 esbonio 关键字，选择远程环境，找到 Esbonio Server：Enable 配置项

使能该配置项后，此时 Esbonio 会默认已经打开了一个包含 Sphinx 项目的文件夹，自动检测并初始化 Sphinx 环境，即使用户没有直接打开 .rst 或 .md 文件，只要工作区中有 Sphinx 项目，Esbonio 就会尝试搜索 Sphinx 项目配置文件 conf.py 并执行初始化

文档构建过程

在下方的工作区，选择【输出】选项卡，右侧下拉框选择【Esbonio】服务器，可看到
在这里插入图片描述

将输出选项卡拖到最下面，会发现构建出错，提示找不到 warnings_filter 扩展
在这里插入图片描述

问题分析&解决

回到 Sphinx 配置文件 conf.py，里面有这么一段话
在这里插入图片描述
里面的注释提示到：如果使用的 Sphinx 扩展不在标准路径下，而是放在某个自定义目录里，就把那个目录加到 sys.path 中，如果是对于 Documentation 的相对路径，建议用 os.path.abspath 转成绝对路径

虽然注释里提到了 os.path.abspath，但下面 39 行代码并没有使用绝对路径，这里就是问题所在，因为现在用的是相对路径 “_extensions”，实际依赖于运行 Sphinx 时所在的目录：

如果当前目录是 Documentation/，那 _extensions 能正确找到，那 _extensions 扩展里面的 warnings_filter 也就能找到了
如果工作目录不是 Documentation/，Python 就找不到 _extensions，也就找不到 warnings_filter 扩展

很明显，对用户而言，期望构建渲染不依赖于当前目录，那么需要对这里进行调整下，使用绝对路径

将 Path setup 部分替换如下

# -- Path setup --------------------------------------------------------------# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import osimport sys# Add the '_extensions' directory to sys.path, to enable finding Sphinx
# extensions within.
import os
# 获取 conf.py 所在目录
_file_path = os.path.dirname(__file__)
_extensions_path = os.path.join(_file_path, '_extensions')
sys.path.insert(0, _extensions_path)
# -- Project information -----------------------------------------------------

保存 conf.py 文件，再次触发 Sphinx 构建，可以看到构建系统已经找到 warnings_filter 扩展，但是找不到另外一个文件 known-warnings.txt
在这里插入图片描述
这个 known-warnings.txt 相当于 warnings_filter 的输入文件，warnings_filter 实现了过滤器部分，而 known-warnings.txt 则定义了要过滤哪些内容

known-warnings.txt 同样在 conf.py 文件里有定义
在这里插入图片描述
同样，将 Options for warnings_filter 部分替换如下

# -- Options for warnings_filter ------------------------------------------
_warnings_filter_config_path = os.path.join(_file_path, 'known-warnings.txt')
warnings_filter_config = _warnings_filter_config_path

在【输出】选项卡可以看到构建成功
在这里插入图片描述
ok，今天先到这里，下篇 blog 继续