sphinx-build 找不到 .rst 文件是因为默认只扫描 source/index.rst 且要求其存在并被 toctree 引用；必须确保 index.rst 存在、含 toctree 指令，新增文件需加入 toctree，文件编码为 utf-8 无 bom。
为什么 sphinx-build 找不到 .rst 文件？
常见现象是执行 sphinx-build -b html source build 后报错 WARNING: no files found，或生成的 HTML 里只有空目录结构。根本原因不是文件没写，而是 sphinx-build 默认只扫描 source/conf.py 所在目录下的 index.rst，且要求它必须存在、且被 toctree 显式引用。
-
source/目录下必须有index.rst，哪怕内容只有一行Welcome -
index.rst里至少要包含一个.. toctree::指令，哪怕只列出自己：.. toctree:: :maxdepth: 1 <p>index</p>
- 新增的
chapter1.rst必须被加进某个toctree指令里，否则 Sphinx 完全忽略它 - Sublime Text 里保存文件时注意编码：必须是 UTF-8（无 BOM），否则
sphinx-build可能静默跳过该文件
Sublime Text 中如何实时预览 RST 渲染效果？
Sublime Text 本身不渲染 RST，但可通过插件 + 外部工具组合实现“保存即刷新”效果。关键不是装一堆插件，而是选对链路。
- 推荐用
SublimeText-RST插件（通过 Package Control 安装），它不渲染，但提供语法高亮、:role:补全、.. directive::折叠等功能，避免手误 - 真正预览靠浏览器 +
sphinx-autobuild：运行sphinx-autobuild -b html source build，它会监听.rst和conf.py变更，自动重建并刷新浏览器页面（默认http://localhost:8000） - 不要用 Sublime 自带的
Build System绑定sphinx-build—— 每次都要手动刷新，且错误堆栈不友好；sphinx-autobuild的终端输出更清晰，比如哪一行缩进错了、哪个角色拼错了 - 如果用 Chrome，建议禁用缓存（DevTools → Network → ✅ Disable cache），否则改了标题也不更新
conf.py 里哪些配置项最容易导致构建失败？
新手常把 conf.py 当成模板直接用，但几个关键路径和布尔值一旦错位，Sphinx 就不报错只静默失效。
-
extensions = ['sphinx.ext.autodoc']这类扩展名必须拼写完全正确，少个ext.或大小写错（如Autodoc）会导致整个扩展加载失败，但sphinx-build不提示 -
source_suffix = '.rst'必须是字符串，不是列表；如果写成['.rst']，Sphinx 会拒绝启动 -
html_theme = 'alabaster'如果主题未安装（比如写了'sphinx_rtd_theme'却没pip install sphinx-rtd-theme），构建会卡在 theme 加载，报错信息藏在最后一行：Theme error: no theme named 'sphinx_rtd_theme' found -
exclude_patterns = ['_build', 'Thumbs.db']如果误写成exclude_pattern（少个 s），该配置直接被忽略，可能导致构建包含不该有的临时文件
如何让 Sphinx 正确识别 Sublime Text 中写的中文标题和代码块？
中文乱码或代码块渲染失败，90% 是编码或语法细节问题，和字体、系统语言无关。
- 所有
.rst文件顶部加声明：.. -*- coding: utf-8 -*-
，这行必须是文件第一行，且不能有任何空格或 BOM - 中文标题层级必须严格对齐：一级标题用
=，二级用-，三级用^，且长度 ≥ 标题文字长度；第一章下面跟===（3 个等号）就错，得是=======（7 个） - 代码块必须用
.. code-block:: python（注意冒号后有空格），不能写成.. code:: python（旧写法已弃用，Sphinx 会当普通段落处理） - 如果代码块里有中文字符串，确保 Python 源码本身也声明了
# -*- coding: utf-8 -*-，否则sphinx.ext.autodoc提取 docstring 时会崩
路径、编码、缩进、冒号后空格——这些地方错一个字符，Sphinx 就可能不报错但不生效。它不像编译型语言那样拦住你，而是默默跳过，所以检查日志里的 WARNING 比看输出更管用。
