6

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

 3 years ago
source link: https://segmentfault.com/a/1190000040801843
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
neoserver,ios ssh client

从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要求代码注释符合谷歌规范。


report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK