共计 1602 个字符，预计需要花费 5 分钟才能阅读完成。
用 python 写了一个屏幕自动控制的开源小我的项目
，须要编写文档，这可能是程序员最苦楚的工作了，哈哈。
为了尽量减少工作量，API 调用局部最好能间接用源码正文生成——这样至多不必写两遍了，而且正文离源码最近，互相对照写起来不便。
摸索了一下生成工具，发现还不是那么简略。目前成熟可用的有三个：
- Pydocs：python 环境自带，然而有点过于简略，只能一个个指定文件 / 类 / 模块来生成文档，生成的内容缺省输入到控制台，还得重定向到文件，劣势是原生反对 Markdown。当然另外两个工具又过于简单了点，没有找到相似 JavaDoc 那样均衡的工具
- Sphinx：老牌文档生成工具，和上面的 MkDocs 一样，都是残缺的文档组织管理工具，能够生成 Html 文档，全套文档要当做一个我的项目来治理。如果要从源码正文生成文档，须要装置 autodoc 等扩大。Sphinx 最大的毛病在于要应用一种叫做 reStructuredText（.rst 文件）的文档格局，很是顺当。详见应用 Sphinx 为我的项目主动生成 API 文档
- MkDocs：绝对新的文档管理工具，通过 Markdown 格局来组织文档，装置插件 Mkdocstrings 当前，也反对从源码正文生成 md 文件。网上也有比拟具体的教程，本文次要补充一点踩过的坑。
首先呢，MkDocs 是把文档当成我的项目来治理的，咱们编写的 markdown 文件，相当于“文档源码”，会被它“编译”成 Html（反对多种格调），而 Mkdocstrings 这个插件，是从 python 源码中提取正文，生成 mk 格局的“文档源码”。
刚接触的时候，咱们可能会犹豫：这个我的项目和本来的 python 我的项目是什么关系呢？其实除了要提取正文，两个我的项目没关系。大能够释怀地在原 python 我的项目里建一个目录，用 mkdocs new 指令新建一个文档我的项目。
新建我的项目当前，mkdocs 会在指定目录下，生成一个 yaml 格局的配置文件，再新建一个 docs 目录，作为“文档源码”所在位置，并且生成一个名为 index.md 的缺省文档。
为了反对正文生成文档，须要 pip 装置 mkdocstrings，然批改 mkdocs.yml 配置文件，启用这个插件
plugins:
- mkdocstrings而后在本人的 md 文件里（或者生成的 index.md，取决于想在哪里生成）用非凡格局引入 python 源码的模块名，例如：
## generated
::: autopy # autopy 是模块名，能够写多级，比方 autopy.core.data 这样，后面的三个冒号，示意这里须要调用 mkdocstrings 来生成之后命令行调用 mkdocs build，会生成相应的 html 文件，或者调用 mkdocs serve 启动一个本地 http 服务器，通过浏览器来预览。此时可能会报错：提醒找不到指定的模块，这很可能是 python 源码没有退出零碎门路造成的。
咱们当然能够把源码门路间接加到 PATHONPATH 环境变量中，但这样会有影响其余程序的副作用，而且还得按绝对路径加，不够灵便。好在 mkdocstrings 配置够弱小，反对动静代码，此时能够补充 mkdocs.yml 文件里补充 handlers：
plugins:
- mkdocstrings
handlers:
python:
setup_commands:
- import sys
- sys.path.insert(0, "..")这里等于通知 mkdocstring，提取正文前，先执行 setup_commands 中的语句，通过 sys.path.insert，把父目录增加进来（咱们后面是在 python 源码目录下，新建了文档我的项目，所以对文档我的项目来说，源码就是父目录）。
再次执行mkdocs serve，就会发现生成的 html 文档中，::: autopy 这部分，曾经被代码中的正文替换掉了。
留神：Mkdocs 要求代码正文合乎谷歌标准。
