Python Sphinx 自动提取注释生成API文档

写在前面：这个库的使用文档百度一查有很多，但是都很乱，而且试了很多教程，很多都不成功，这篇文章是在多次尝试后才成功实现，现记录下来，以供参考。

一、效果演示

图一 首页

       图二 contents/src/demo module

图三 索引

图四 模块索引

图五 搜索

二、Demo源码

"""
这个脚本用于演示Sphinx效果
"""


def calc_sum(num1: int, num2: int) -> int:
    """
    计算两数和

    :param num1: 加数1
    :param num2: 加数2
    :return: 两数和

    Example:

    >>> calc_sum(2, 3)
    5
    """
    return num1 + num2


def calc_sub(num1: int, num2: int) -> int:
    """
    计算两数差

    :param num1: 被减数
    :param num2: 减数
    :return: 两数差

    Example:

    >>> calc_sub(5, 3)
    2
    """
    return num1 - num2


if __name__ == '__main__':
    print(f'2 + 3 = {calc_sum(2, 3)}')
    print(f'5 - 2 = {calc_sub(5, 2)}')

三、测试环境

Python版本：Python 3.7.9

Sphinx：

Sphinx
Sphinx                        5.3.0
sphinxcontrib-applehelp       1.0.2
sphinxcontrib-devhelp         1.0.2
sphinxcontrib-htmlhelp        2.0.0
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          1.0.3
sphinxcontrib-serializinghtml 1.1.5

Sphinx实际上只需要执行一句安装命令即可（如下），其余会自动安装，列出来仅供版本参考

pip install Sphinx

四、文档生成步骤

1. 项目目录结构

初始目录只需要建立src和docs即可，docs中的文件是执行完后续步骤自动生成的。

2. 步骤

（1）打开控制台，切换到docs目录

（2）执行sphinx-quitstart，这会触发引导，参考下图进行填写，除了图中需要修改，其他默认就行。

（3）修改SphinxDemo/docs/conf.py

修改如下部分：

（4）将源码生成.rst文件

还是在docs目录下，执行命令：

sphinx-apidoc -o ../doc ../src/

表示：将../src目录下的py文件生成rst文件，生成到../doc目录

（5）生成HTML文档

执行命令：

make html

 至此，html已生成完毕，可以在SphinxDemo\docs\_build\html中查看，点击Index.html即可在浏览器打开。

五、其他

 Sphinx还可以进行主题更换等其他操作，例如换成跟PyPi一样的蓝白主题，有些需要下载其他的库进行补充，自行探索。