Sublime Text安装并配置Sphinx科技文档本地预览-sublime-PHP中文网

能跑通sphinx本地预览的关键是sphinx-autobuild链路打通、路径编码干净、index.rst存在且被toctree引用；需安装sphinx和sphinx-autobuild，终端运行sphinx-autobuild监听变更，确保index.rst为utf-8无bom并含toctree，sublime插件仅提供语法支持，构建问题须查终端日志。

sublime text安装并配置sphinx科技文档本地预览

能跑通 Sphinx 本地预览，关键不在 Sublime 插件装得多，而在 sphinx-autobuild 链路打通、路径编码干净、index.rst 存在且被引用——三者缺一不可。

确认 sphinx-autobuild 可执行且监听生效

Sublime 自带的 Ctrl+Shift+R 预览本质是调用 sphinx-build 一次性构建，不监听变更；真正“保存即刷新”必须靠终端运行 sphinx-autobuild。

先装完整环境：pip install sphinx sphinx-autobuild（只装 docutils 不够，数学公式、自定义角色会失效）
终端进入你的文档根目录（含 conf.py 的目录），运行：sphinx-autobuild -b html source build（假设源码在 source/ 下）
若报错 command not found: sphinx-autobuild，说明没装或 PATH 没生效；Windows 用户检查是否勾选了安装时的 “Add Python to PATH”
成功后浏览器打开 http://localhost:8000，改任意 .rst 文件并保存，页面应自动刷新

确保 index.rst 存在、UTF-8 无 BOM、含 toctree

Sphinx 默认只认 source/index.rst，且必须被 toctree 指令显式包含，否则新增文件全被忽略——这不是插件问题，是 Sphinx 本身行为。

Sublime Text Build Linux版

Sublime Text Linux x86-64 deb 安装包。官方也提供 rpm、tar.xz 和软件源安装方式。

下载

手动创建 source/index.rst，内容至少包含：
```
.. toctree::
   :maxdepth: 1

   index
```
所有其他 .rst 文件（如 chapter1.rst）必须加进某个 toctree 指令里，哪怕只是写在 index.rst 中
Sublime 中右下角状态栏点击编码名 → 选 UTF-8（不是 UTF-8 with BOM），中文路径务必避免（例如 C:/我的文档/docs 会导致 sphinx-autobuild 静默退出）

Sublime 的 reStructuredText 插件只负责语法支持，不负责构建

插件名是 reStructuredText（不是 rst 或 rest），它只提供高亮、指令折叠、:role: 补全等功能，和预览无关。

安装方式：Ctrl+Shift+P → Package Control: Install Package → 输入 reStructuredText → 回车
若打开 .rst 文件后右下角显示 Plain Text，需手动点击状态栏切换为 reStructuredText
如果用了 Anaconda/pyenv/虚拟环境，需在 Preferences → Package Settings → reStructuredText → Settings – User 中指定解释器：{"python_binary": "C:/path/to/python.exe"}（Windows 路径用正斜杠）
别指望它解决构建失败；错误堆栈永远在终端里，不是 Sublime 控制台（Ctrl+`）

Chrome 预览时禁用缓存，conf.py 里别写错 source_suffix

浏览器缓存会让修改后的标题、段落不更新；conf.py 中一个字符写错，Sphinx 就可能静默跳过整个构建流程。

Chrome 打开 DevTools（F12）→ Network 标签页 → 勾选 Disable cache
source_suffix = '.rst' 必须是字符串，不是列表；写成 ['.rst'] 会导致 sphinx-autobuild 启动失败且无明确提示
extensions 列表中扩展名必须全小写、带完整路径，例如 'sphinx.ext.autodoc' 写成 'autodoc' 或 'Sphinx.ext.autodoc' 都会加载失败