sphinx为源码生成文档

1. 安装

pip install sphinx

2. 创建项目

3. 初始化文档

在sphinx_usage目录下创建两个目录doc和src。doc放文档，src放代码。
sphinx-quickstart
一步步设置

4. 修改conf.py文件

• 指定源码文件

 import os
 import sys
 sys.path.insert(0, os.path.abspath('../../src'))

• 添加扩展

extensions = ['sphinx.ext.autodoc',
              'sphinx.ext.doctest',
              'sphinx.ext.intersphinx',
              'sphinx.ext.todo',
              'sphinx.ext.coverage',
              'sphinx.ext.mathjax',
              'sphinx.ext.napoleon'
              ]

• 修改主题

html_theme = 'sphinx_rtd_theme'

5. 为源码生成API文档

写代码 src/demo.py

#coding=UTF-8
class Demo1():
    """类的功能说明"""

    def add(self,a,b):
        """两个数字相加，并返回结果"""
        return a+b

    def google_style(arg1, arg2):
        """函数功能.

        函数功能说明.

        Args:
            arg1 (int): arg1的参数说明
            arg2 (str): arg2的参数说明

        Returns:
            bool: 返回值说明

        """
        return True

    def numpy_style(arg1, arg2):
        """函数功能.

        函数功能说明.

        Parameters
        ----------
        arg1 : int
            arg1的参数说明
        arg2 : str
            arg2的参数说明

        Returns
        -------
        bool
            返回值说明

        """
        return True

为源码生成API文档：
sphinx-apidoc -o ./source ../src

6. make html

在doc目录下执行：

make clean
make html

make clean是清空之前生成在build目录下的html文件
make html是把.rst文件生成html文件