【聲明】本博客所有內容均為個人業余時間創作，所述技術案例均來自公開開源項目（如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 再詳細分析下這些擴展的安裝