根本原因是模块未被Python正确导入；Sphinx运行独立解释器，需在conf.py中添加项目根路径到sys.path，并验证import成功，再配置autodoc选项与mock依赖。
用 sphinx 生成 API 文档，但 autodoc 不生效？
根本原因通常是模块没被 Python 正确导入，不是配置写得不对。Sphinx 运行时会启动一个独立的 Python 解释器环境，sys.path 和你本地开发环境不一致。
- 在
conf.py里显式追加项目根路径：import os<br>import sys<br>sys.path.insert(0, os.path.abspath('..')) # 假设源码在 docs 同级目录 - 确保目标模块能被直接
import：在终端进到docs/目录后，运行python -c "import mypackage; print(mypackage.__file__)"，失败就别指望autodoc成功 -
autodoc_default_options推荐设为{'members': True, 'undoc-members': True, 'show-inheritance': True}，否则连 public 方法都不显示 - 如果模块依赖 C 扩展或特定环境变量（比如
torch），Sphinx 构建时可能静默跳过——加autodoc_mock_imports = ["torch", "tensorflow"]避免报错，但注意这会让类型提示失效
pydoc-markdown 比 sphinx 轻，适合什么场景？
适合单文件、小工具、CLI 脚本这类“写完就发 GitHub”的项目，不需要多页导航、主题定制或中文 PDF 输出。
- 它靠解析 AST 提取 docstring，不执行代码，所以不怕 import 报错，也不需要
sys.path手动调整 - 默认只处理模块级和函数级 docstring，类方法要加
--render-toc和--include-private才可能看到_helper()这种 - 输出是纯 Markdown，可直接丢进 GitHub README 或 Notion，但无法生成交叉引用链接（比如点击函数名跳转到定义）
- 对 type hint 支持较弱：
def foo(x: list[str]) -> None:会被渲染成x: <class></class>，除非加--eval-type-hints（有安全风险，慎用）
文档里想自动插入代码片段，又不想手动复制粘贴？
用 sphinx.ext.viewcode 是最省事的方案，但它只给「已导入的符号」生成跳转链接；真要嵌入片段，得靠 sphinx.ext.includecode 或第三方扩展 sphinxcontrib-napoleon + 手动标注。
.. includecode:: ../src/mymodule/utils.py<br> :start-after: # START example<br> :end-before: # END example
—— 片段靠注释锚点定位，维护成本低，但注释必须严格匹配- 别用
.. literalinclude::直接塞整个文件，容易把测试代码、TODO 注释、调试print()一起带进去 - 如果片段含动态值（比如版本号、时间戳），
includecode无能为力，得写个自定义 Sphinx directive，在run()里调用subprocess.run()临时生成内容 - 所有 include 类指令都受
source_suffix影响：默认只认.py，加.md或.sh要额外配pygments_lexer
CI 里自动生成文档并部署，常见断点在哪？
不是构建失败，而是生成结果和本地不一致——最常出在 Python 版本、依赖版本、工作目录三处。
立即学习“Python免费学习笔记（深入）”；
- GitHub Actions 默认用
ubuntu-latest，Python 是 3.12，但你的pyproject.toml可能锁了python = "^3.9"，导致pip install -e .失败 -
pip install sphinx sphinx-rtd-theme必须在安装项目包之后执行，否则autodoc看不到你的模块 -
make html输出默认在_build/html/，但有些 CI 模板硬编码了public/，结果推上去的是空页面 - 中文文档记得加
language = 'zh_CN'和html_search_language = 'zh'，否则搜索框不能分词，搜“配置”找不到“配置项”
事情说清了就结束。文档自动化最难的从来不是工具链拼接，而是让 docstring 写得既准确又不冗余，以及每次改代码时顺手更新它。
