需安装sublime-rst-completion插件实现.rst文件语法高亮与基础补全，装后右下角应显示reStructuredText；预览依赖Sphinx，通过SublimeOnSaveBuild配置make html自动构建并刷新浏览器。
Sublime Text 里怎么让 .rst 文件有语法高亮和基础补全
默认安装的 Sublime Text 不认识 .rst 文件，打开就是纯文本。得装插件才能识别语法、缩进、标题层级。
推荐装 sublime-rst-completion：它不只是补全，还自带基础语法高亮、大纲视图（侧边栏显示标题结构）、常用指令快捷插入（比如 .. code-block:: python）。
- 用
Package Control → Install Package搜索并安装sublime-rst-completion - 装完后，新建或打开
index.rst，右下角状态栏应显示reStructuredText，不是Plain Text - 如果没自动切换，手动点击状态栏 →
ReStructuredText→ 确保选中 - 别装
RestructuredText（老版本，已停更），它和sphinx配合不好，容易卡顿或补全失效
怎么在 Sublime Text 里实时预览 rst 内容效果
Sublime Text 本身不渲染 HTML，但可以调用 Sphinx 快速构建并自动刷新浏览器预览——关键在于配置好 make 命令路径和监听逻辑。
先确认你本地已安装 Sphinx 并能运行：sphinx-build -b html source build/html 成功，说明环境就绪。
- 安装
SublimeOnSaveBuild插件：保存.rst时自动触发构建 - 在项目根目录（含
source/conf.py）下，创建sublime-build配置文件，内容类似：
{
"cmd": ["make", "html"],
"working_dir": "${project_path}",
"selector": "source.rst"
}
保存为 Sphinx.sublime-build，放在 Packages/User/ 目录下。之后按 Ctrl+Shift+B（Win）或 Cmd+Shift+B（Mac）选择它即可构建。
注意：make 在 Windows 上可能叫 make.bat，路径要写对；若报错 'make' is not recognized，说明没把 Sphinx 的 Scripts 目录加进系统 PATH。
为什么修改 conf.py 后预览不更新？常见路径陷阱
Sphinx 构建依赖 conf.py 中的 source_dir 和 build_dir 路径设置。Sublime 默认只监听 .rst 文件变化，但 conf.py 修改后不会自动 rebuild，必须手动触发。
-
conf.py里source_dir = 'source'是硬编码路径，别写成./source或绝对路径，否则 Sublime 构建时找不到源文件 -
html_static_path = ['_static']这类路径是相对于source_dir的，不是项目根目录 - 如果改了
extensions列表（比如加了sphinx-autodoc），必须重启构建过程，缓存不会自动清空 - 建议在
conf.py开头加一行import os; print('Sphinx loading from:', os.getcwd())，确认当前工作目录是否是你期望的项目根目录
如何让 Sphinx 自动加载 Python 模块并生成 API 文档
光写 .rst 不够，要让 Sphinx 把代码里的 docstring 变成文档，得靠 sphinx-autodoc 扩展，且 Python 模块必须能被 import。
- 在
conf.py的extensions列表里加上'sphinx.ext.autodoc' - 确保项目根目录（或
conf.py所在目录）能直接import yourpackage—— 最简单办法是执行pip install -e .（项目有setup.py或pyproject.toml） - 在
source/api.rst里写：
.. automodule:: yourpackage.module :members: :undoc-members:
然后在 source/index.rst 的 toctree 里加入 api，构建时才会包含。
容易漏的一点：autodoc_default_options = {'members': True, 'undoc-members': True} 加到 conf.py 里，不然每个 automodule 都得重复写选项。
最后提醒一句：Sphinx 构建是“静态快照”，它不会监听 Python 源码变化。改了代码 docstring，必须重新运行 make html 才生效——这点和 VS Code 的实时预览插件逻辑完全不同。
