一、参考资料

从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)

在 index.rst中修改如下：

.. toctree::
   :maxdepth: 2

   test/test

5. 编译

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

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

注意事项

关于图片的引用，sphinx会自动将图片文件移动到_images文件夹下，不同文件夹下的图片都会移动到这个文件夹下，图片名称不建议使用中文名称，会导致无法正常移动图片。
关于图片不同文件夹下名称相同，移动后会将同名的文件进行重命名，添加序号之类的，因此不会影响实际显示效果。
关于部分md文档中标题无法在目录中正常显示问题，需要在conf.py文件中添加如下配置：
```
html_theme_options = {"collapse_navigation": True, "navigation_depth": 6}
```