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

背景

接之前 blog
【OS】【Nuttx】【周边】文档构建渲染：安装 Esbonio 服务器
已安装好了 Esbonio 服务器，但此时还用不了，需要配置和特殊操作一下，下面来分析下

Sphinx 配置文件

上篇 blog 已经介绍了 Esbonio 服务器的安装，下面先来检查下，终端输入

ls -l ~/.local/bin/

可以看到可执行文件 esbonio

可见虽然是用 python3 -m 来安装的 python 模块（其源码部分在 ~/.local/lib/python3.12/site-packages/），但实际上也生成了可执行部分，可以在终端运行，在终端输入

esbonio --version

可以查看其版本号

终端输入

cat ~/.local/bin/esbonio

可以看到可执行文件 esbonio 的实现

• 其实现也是用的 python 脚本
• 用的 python3 解释器，从 esbonio 包的 __main__.py 文件中导入 main 函数
• 这个 main() 函数是 esbonio 命令行工具的真正入口点，负责解析命令行参数、启动语言服务器等

当然因为安装了 esbonio 扩展，这里可以不用手动在终端里面输入命令来启动 esbonio 服务器，只需要在 esbonio 扩展里面配置一下即可

conf.py

在配置 Esbonio 服务器之前，首先要了解一个文件 conf.py

• conf.py 是 Sphinx 的配置文件（文档引擎配置），位于项目根目录 Documentation 下，Sphinx 是一个用 Python 写的文档生成器，能把 .rst 或 .md 文本文件，变成漂亮的，符合人们阅读习惯的文档网站
• conf.py 的文件名固定，必须叫 conf.py，换名字会导致 Sphinx 识别不出来
• conf.py 的位置通常在文档目录下，比如这里的 Documentation 目录
• sphinx-build 命令在构建渲染文档的时候，Sphinx 引擎会读取 conf.py，把 .rst 文件变成 HTML/PDF/静态网站 等输出
• Esbonio 可以读取并理解 Sphinx 项目中的 conf.py 配置，可以自动触发 Sphinx 构建过程，比如当保存 .rst 文件时，Esbonio 可以自动调用 Sphinx 来重新生成文档，确保能够快速看到更改效果，通过 Esbonio 和 Sphinx 的结合，能很方便地预览最终渲染的文档效果

另外，要提前把 conf.py 里面的这些扩展安装好

下面简单介绍下这几个扩展：

• sphinx_rtd_theme：网站主题 Read the Docs，用来美化文档外观，包括文档网站是左侧目录，右侧内容的经典布局，支持搜索等
• myst_parser：支持用 Markdown 语言，.md 文件来写 Sphinx 文档，相当于给 Sphinx 装了个 Markdown 插件，让 Sphinx 引擎也能读取 .md 文件
• sphinx.ext.autosectionlabel：自动为每个章节标题创建引用标签，方便链接跳转
• sphinx.ext.todo：支持写待办事项列表，可以控制是否显示
• sphinx_tabs.tabs：在文档中插入可切换的标签页
• sphinx_copybutton：在代码块右上角添加复制按钮，点击就能复制代码，对读者非常友好，尤其是复制命令行指令时，提升用户体验
• warnings_filter：过滤掉不关心的 Sphinx 警告信息

ok，下篇 blog 再详细分析下这些扩展的安装