不能，因为mkdocs本身不解析Python代码，必须安装mkdocstrings插件并在mkdocs.yml中正确配置handlers、python_path等参数，否则API文档无法生成。
能，但必须加插件，纯 mkdocs 本身不解析 Python 代码，mkdocstrings 是关键桥梁。
为什么直接用 mkdocs build 无法生成 API 文档？
因为 mkdocs 的核心逻辑只读取 .md 文件并渲染成 HTML，它完全不扫描你的 .py 源码。即使你在 calculations.py 里写了完整的 Google 风格 docstring，mkdocs build 也视而不见——它没这个能力。
- 常见错误现象：
mkdocs serve页面里出现{{ calculator.add }}这类原始模板字符串，而不是函数说明和参数表 - 根本原因：没启用
mkdocstrings插件，也没在mkdocs.yml中配置 Python 解析器 - 对比验证：删掉
plugins里的mkdocstrings，再运行mkdocs build，API 页面会变成空白或报Unable to resolve cross-reference
mkdocstrings 插件怎么配才真正生效？
光 pip install mkdocstrings mkdocstrings-python 不够，YAML 配置漏掉任意一项都会导致解析失败。
- 必须在
mkdocs.yml的plugins下明确声明：- mkdocstrings（不能只写mkdocstrings或拼错） - 必须指定
handlers，例如：python: default，否则插件不知道该用哪种规则解析你的模块 - 确保
docs/下的 Markdown 文件里用的是正确引用语法，比如{{ calculator.calculations.add }}（路径需与实际包结构一致） - 如果项目用了
src/目录布局（即 Python 包不在根目录），得在mkdocs.yml里加python_path: ["src"]，否则插件找不到模块
本地预览时 API 文档不刷新怎么办？
mkdocs serve 默认只监听 docs/ 和 mkdocs.yml，改了 .py 文件不会触发重建——这是最常被忽略的坑。
立即学习“Python免费学习笔记（深入）”；
- 解决方案：启动时加
--watch-theme并手动指定额外监听路径，例如：mkdocs serve --watch docs/ --watch src/ --watch mkdocs.yml - 更稳妥的做法：用
mkdocs serve+watchmedo自动重载，避免每次改完代码都手动 Ctrl+C 再重启 - 注意
mkdocstrings缓存：首次加载后，修改 docstring 可能仍显示旧内容，需清空.mkdocstrings-cache/目录或加cache: false到 handler 配置中
部署到 GitHub Pages 后 API 页面 404？
不是路径写错，而是构建时 Python 模块导入失败——mkdocs gh-deploy 在 CI 环境里没有你的项目源码路径。
- 关键动作：CI 脚本里先
pip install -e .（确保可 import）或把src/加入PYTHONPATH - 检查
site/api.md是否生成了真实 HTML 内容，还是空 div 或报错信息；如果是后者，说明构建阶段mkdocstrings已静默失败 - 避免相对导入陷阱：
from .utils import helper在文档构建时会报ImportError，改用绝对导入from mypackage.utils import helper
真正卡住人的从来不是安装命令，而是插件配置和路径映射那几行 YAML —— 少一个冒号、多一个缩进、路径少一级，API 文档就彻底消失。动手前先确认 python -c "import your_package" 能成功，再谈文档生成。
