从Python源码注释，自动生成API文档

用python写了一个屏幕自动控制的开源小项目
，需要编写文档，这可能是程序员最痛苦的工作了，哈哈。
为了尽量减少工作量，API调用部分最好能直接用源码注释生成——这样至少不用写两遍了，而且注释离源码最近，相互对照写起来方便。

摸索了一下生成工具，发现还不是那么简单。目前成熟可用的有三个：

1. Pydocs：python环境自带，但是有点过于简单，只能一个个指定文件/类/模块来生成文档，生成的内容缺省输出到控制台，还得重定向到文件，优势是原生支持Markdown。当然另外两个工具又过于复杂了点，没有找到类似JavaDoc那样平衡的工具
2. Sphinx：老牌文档生成工具，和下面的MkDocs一样，都是完整的文档组织管理工具，可以生成Html文档，全套文档要当做一个项目来管理。如果要从源码注释生成文档，需要安装autodoc等扩展。Sphinx最大的缺点在于要使用一种叫做reStructuredText（.rst文件）的文档格式，很是别扭。详见使用 Sphinx 为项目自动生成 API 文档
3. 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要求代码注释符合谷歌规范。