API文档自动生成工具

一、参考资料

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

二、问题引入

不管是开源还是闭源，要让所有人都能读懂你的代码这太难了，所以文档是很重要的。大部分情况，我们不希望维护一份代码再加上一份文档，这样做很容易造成文档和代码的不一致，程序员最讨厌更新文档了。

为了尽量减少工作量，API调用部分最好能直接用源码注释生成——这样至少不用写两遍了，而且注释离源码最近，相互对照写起来方便。

三、Pydocs

python环境自带，但是有点过于简单，只能一个个指定文件/类/模块来生成文档，生成的内容缺省输出到控制台，还得重定向到文件，优势是原生支持Markdown。

四、Sphinx

使用 Sphinx 为项目自动生成 API 文档

How-To Guides

Sphinx 使用手册

Learn reStructureText

RST 中文文档 v2.0.2

Sphinx doc官网

老牌文档生成工具，和MkDocs一样，都是完整的文档组织管理工具，可以生成Html文档，全套文档要当做一个项目来管理。如果要从源码注释生成文档，需要安装autodoc等扩展。Sphinx最大的缺点在于要使用一种叫做**reStructuredText（.rst文件）**的文档格式，很别扭。

1. RST

reStructuredText (RST、ReST或reST)一种用于文本数据的文件格式，基于 Python 的 docutils 模块提供解析功能的标记语言。

2. 常用指令

# 查看Sphinx版本
sphinx-build --version

3. 关键步骤

3.1 安装Sphinx

pip install sphinx
sudo apt install python3-sphinx

3.2 设置文档源目录

在同一个项目中维护代码和文档，需要在项目根目录新建一个 docs 文件夹（也可以使用其他名称），用来存放所有和文档有关的文件，我们将使用该文件夹作为 Sphinx 工作的源目录（source directory）。

mkdir docs
cd docs

# 初始化文档项目
sphinx-quickstart

docs
├── build # 存放生成的文档
│   ├── doctrees
│   └── html
├── make.bat
├── Makefile
└── source # 存放Sphinx工程源码
    ├── api_python
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates

解释说明：

• conf.py 配置文件，整个项目的配置文件，可以配置插件、主题、项目名称、中英文等。
• Makefile 和 make.bat 编译所需脚本，在 docs 目录执行 make html 即可通过源文件生成静态网页。
• index.rst 是文档源文件的首页，文档里有一些默认的样板内容，通常我们将其作为访问其他页面的入口目录。
• build 文件夹下存放的是编译后产生的文件

3.3 生成文档

运行 make html 生成静态网页用于预览，生成的 HTML 页面保存在 build/html 目录。

make html

4. Markdown支持

python sphinx(文档生成器)入门

4.1 安装markdown支撑的模块

pip install myst-parser

4.2 安装md文档相关主题

pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx-markdown-tables

4.3 设置插件

在conf.py文件中设置extensions字段添加md文档处理。

extensions = ["recommonmark"]

4.4 新建md文件

下面在source文件夹下新建一个子文件夹叫test, 里面存放md文档相关数据，此处新建一个test.md文档，内容如下:

## 简介
## 测试图片

![avatar](../images/test/test.gif)
![avatar](../images/test2/test.gif)
![avatar](../images/test2/test.jpg)

4.5 在主目录中添加md文件目录

在 index.rst中修改如下：

.. toctree::
   :maxdepth: 2

   test/test

5. 编译

在项目根目录下执行如下命令转为html

# 需要注意windows是bat文件
make html

注意事项

1. 关于图片的引用，sphinx会自动将图片文件移动到_images文件夹下，不同文件夹下的图片都会移动到这个文件夹下，图片名称不建议使用中文名称，会导致无法正常移动图片。

2. 关于图片不同文件夹下名称相同，移动后会将同名的文件进行重命名，添加序号之类的，因此不会影响实际显示效果。

3. 关于部分md文档中标题无法在目录中正常显示问题，需要在conf.py文件中添加如下配置：

   html_theme_options = {"collapse_navigation": True, "navigation_depth": 6}
   

6. 应用案例

MindSpore的教程和API文档均可由Sphinx工具生成。

五、MkDocs

MkDocs是相对新的文档管理工具，通过Markdown格式来组织文档，安装插件Mkdocstrings以后，也支持从源码注释生成md文件。

六、Doxygen

参考资料

干货|教你使用Doxygen制作漂亮的程序文档

Doxygen文档生成工具教程

文档生成神器—doxygen的使用和代码注释规范

自定义Doxygen生成小而美的文档