在python代码中我们使用文档注释，然后再通过使用sphinx就可以生成相关的文档了。下面详细介绍下相关步骤：

  1. 假设我们已经存在了一个项目名为doc_test，项目下存在一个src文件夹，里面存放我们的源代码。
  2. 安装sphinx
pip install sphinx
  1. 创建文档生成的文件夹
    创建一个名为doc的文件夹，用来存放生成文档的脚本及文档存储。
  2. 生成文档配置及执行脚本
    在doc文件夹下执行如下操作：
sphinx-quickstart
... 接下来会出现下面的配置，可根据自己的项目情况填写
> Separate source and build directories (y/n) [n]: y
> Project name: test
> Author name(s): fcat
> Project release []: 1.0.0
> Project language [en]: zh-CN
  1. 执行完之后会在doc文件夹下生成make.bat的文件，说明上面命令执行完成
  2. 修改配置文件
    为了让能够支持文档自动生成还需要对 doc/source/conf.py进行修改
  • 支持文档自动生成
    修改conf.py的33行的extensions， 自动生成的是extensions = []，需要将其更改为extensions = [‘sphinx.ext.autodoc’]，否则后续执行会报错。
  • 配置源代码路径
    将conf.py中的13-15行注释去除，并将15行修改为以下代码：
sys.path.insert(0, os.path.abspath('./../../src'))
  1. 生成rst文件
    命令行切换到doc目录下，执行如下命令：
sphinx-apidoc -o ./source ../src/
  1. 生成文档的html
    命令行保持在doc目录下，执行如下命令：
make html
  1. 执行完毕后会生成doc/build/html/index.html，则表示文档生成成功。