Sphinx 是本地文档构建工具，Read the Docs 是托管平台；常见问题包括 PATH 未配置导致命令找不到、插件版本不兼容、readthedocs.yml 路径或缩进错误、RTD 版本未激活及构建日志被忽略。
Sphinx 和 Read the Docs 是 Python 项目文档自动化生成与托管的主流组合，但它们定位不同：前者是本地构建工具，后者是托管平台。直接装完就跑通往往失败，关键在环境隔离、配置对齐和构建触发逻辑。
pip install sphinx 失败或命令未找到？检查 Python 环境与可执行路径
常见现象：sphinx-build: command not found（macOS/Linux）或 'sphinx-build' is not recognized（Windows），即使 pip install sphinx 显示成功。
- 根本原因不是没装，而是没进 PATH：Sphinx 安装后生成的可执行脚本（如
sphinx-build）默认放在虚拟环境的bin/（macOS/Linux）或Scripts\（Windows）目录下，未被 shell 自动识别 - 验证是否真装上了：
python -m sphinx --version—— 这种调用方式绕过 PATH，只要 Python 能 import 就能运行 - 修复 PATH（推荐）：
source .venv/bin/activate（Linux/macOS）或.venv\Scripts\activate.bat（Windows），确认提示符前有(.venv) - 不建议全局安装：
pip install --user sphinx会把二进制放到用户级bin，但需手动加到 PATH，易出错
conf.py 配置里 extensions 报错 ModuleNotFoundError？注意依赖包版本兼容性
比如启用 sphinx.ext.autodoc 后报 ModuleNotFoundError: No module named 'sphinx.util.typing'，或 sphinx-rtd-theme 渲染失败。
- 这是 Sphinx 4.x+ 和旧版插件/主题不兼容的典型表现；
sphinx-rtd-theme 不支持 Sphinx 7.x - 推荐锁定组合：
sphinx==7.3.7+sphinx-rtd-theme==2.0.0+sphinx-autobuild==2024.9.1（截至 2026 年 4 月最新稳定搭配） -
extensions列表中不要写错名：'sphinx.ext.viewcode'不是'sphinx.viewcode'，少个ext.就会 import 失败 - 如果用
autodoc，必须确保目标模块已安装到当前环境：pip install -e .（项目含setup.py或pyproject.toml）
readthedocs.yml 配置无效？构建失败常因 Python 版本或 requirements 文件路径不对
Read the Docs 后台构建时提示 Could not find configuration file 或 No module named 'myproject'，不是代码问题，而是构建上下文没配对。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
-
readthedocs.yml必须放在仓库根目录，且文件名全小写、无扩展名错误（不是readthedocs.yaml或.readthedocs.yml） -
python: version: 3.12要和你本地测试用的版本一致；RTD 目前对 3.13 支持不稳定，建议用 3.12 -
submodules: include: true如果文档依赖子模块（如docs/_ext），漏掉这行会导致自定义扩展加载失败 -
requirements: file: docs/requirements.txt—— 路径是相对于仓库根的，不是相对于readthedocs.yml所在位置
本地预览正常，RTD 构建却空白或 404？检查 HTML 输出路径与版本标签同步
RTD 默认构建 latest 分支，但如果你只推了 main 分支且没设置默认版本，它可能拉空分支或跳过构建。
- 进入 RTD 项目 Settings → Versions，勾选你要构建的分支（如
main）并设为 Active；latest对应默认分支，不是“最新版”语义 - HTML 输出默认在
_build/html/，但 RTD 会自动部署到https://<project>.readthedocs.io/en/<version>/</version></project>；若访问/en/latest/404，先确认该版本是否 build status 是Success - RTD 不会自动 rebase 或 force-push：改了
conf.py后必须提交 push，它才触发新构建；Webhook 没配好时，需手动 Trigger Build - 本地用
sphinx-autobuild预览时路径是http://localhost:8000，和 RTD 域名结构无关，别混淆两者部署逻辑
Sphinx 的配置项多而琐碎，conf.py 里一个 html_theme_options 缺少必填 key，或 readthedocs.yml 中缩进多一个空格，都可能导致静默失败——构建日志里藏了真正线索，别只盯着浏览器 404。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
