104、【OS】【Nuttx】【周边】文档构建渲染：安装 Sphinx 扩展（上）
【声明】本博客所有内容均为个人业余时间创作，所述技术案例均来自公开开源项目（如Github，Apache基金会），不涉及任何企业机密或未公开技术，如有侵权请联系删除
背景
接之前 blog
【OS】【Nuttx】【周边】文档构建渲染：安装 Esbonio 服务器
【OS】【Nuttx】【周边】文档构建渲染：Sphinx 配置文件
已安装好了 Esbonio 服务器，并介绍了 Sphinx 配置文件 conf.py，其中提到了需要安装一些必要的扩展文件，下面再详细展开下
Sphinx 扩展
首先还是这几个扩展
下面来介绍这些扩展的安装和配置
sphinx_rtd_theme
作用：Read the Docs 主题，美化文档网站页面
安装：终端输入
python3 -m pip install --user sphinx-rtd-theme --break-system-packages
可以看到安装时会检查依赖项
终端输入
pip show sphinx-rtd-theme
可以看到 sphinx-rtd-theme 扩展的官方信息
- 如果缺少依赖项，自行安装下
- 可以看到，安装位置是用户环境 .local，因为安装时加了选项 --user
- 安装完 sphinx-rtd-theme 扩展之后，还要在 conf.py 里面选择一下网站主题，需要设置一下 html_theme 为 sphinx_rtd_theme（注意，包名是短横线，扩展 extensions 和主题 html_theme 都是下划线）
这里提前展示下最终的文档渲染效果，可以看到 Read the Docs 主题还是可以的，有搜索框，左侧目录，右侧内容，颜色也分配合理，看着舒服（其实和官方网站上看得一样，只不过这里是本地构建，构建渲染后可以不用联网也能查看）
查看 Read the Docs 官网链接 https://docs.readthedocs.com/platform/stable/，可以发现其风格可谓是如出一辙
当然除了 sphinx-rtd-theme 主题，Sphinx 还支持一些其他主题，如 furo，sphinx-book-theme，pydata-sphinx-theme 等，都需要安装对应的扩展，然后设置 html_theme 主题，这里就不深入探索了
myst_parser
作用：支持用 Markdown 语言，.md 文件来写 Sphinx 文档
安装：终端输入
python3 -m pip install --user myst-parser --break-system-packages
安装完成后，终端输入
pip show myst-parser
可查看 myst-parser 的官方信息
可以看到 conf.py 中支持的源文件有 .rst 文件和 .md 文件
sphinx.ext.autosectionlabel
作用：自动为每个章节标题创建引用标签
sphinx.ext.autosectionlabel 是 Sphinx 项目自带的标准扩展，包含在安装 Sphinx 时的主包中，不需要额外安装任何第三方包，在终端中输入
ls ~/.local/lib/python3.12/site-packages/sphinx/ext/
可以看到 autosectionlabel 扩展的实现
这里可以看到 conf.py 设置了前缀 prefix
autosectionlabel_prefix_document 变量设置为 True 很有用，表示为每个章节自动生成的标签加上文件路径前缀，避免标题重复导致的引用冲突
今天先到这里吧，下篇 blog 继续