使用sphinx自动建立API文档（一）

1、使用 demo 的 python 文件

建立test_demo为根目录，下面分别建立doc和src文件夹。

image.png

doc：之后用来存储生成的 html 文件和相关配置
src：源 python 文件
src下面的 demo 文件分别有如下内容：
demo1:

class Demo1():
    """
    English Demo1.
    """
    def demo1(self, arg1):
        """
        Some basic information.

        :param str arg1: this is a arg.(has str type)
        :return: some thing
        """
        print('demo1')
    def run(self):
        """
        Automatically generate documents.

        :return:
        """
        print('run')
class Demo1_ch():
    """
    中文 Demo1.
    """
    def demo1_ch(self, arg1):
        """
        一些基本信息

        :param arg1: 这是一个参数(没有 str 字符类型)
        :return: 信息
        """
        print('demo1_ch')
    def run(self):
        """
        自动生成文档

        :return:
        """
        print('run')

demo2:

def demo2_func(arg1):
    """
    This is a test of function.

    :param str arg1: this is a arg.(has str type)
    :return: some thing
    """
    pass
def demo2_func_ch(arg1):
    """
    一些基本信息

    :param arg1: 这是一个参数(没有 str 字符类型)
    :return: 信息
    """
    pass

2、建立基本的 sphinx 文件

cd到doc目录下。
输入命令：sphinx-quickstart，会弹出一些选项问题。

> Separate source and build directories (y/n) [n]: y
> Name prefix for templates and static dir [_]:
> Project name: demo
> Author name(s): longgb246
> Project release []: 1.0
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:

上面是我的配置，这些之后都可以在doc/source/conf.py 文件中修改。
注意：autodoc: automatically insert docstrings from modules (y/n) [n]: y需要设置为y。

image.png

上面设置对应于doc/source/conf.py 中，相应的插件。

生成的文件结构如下：

image.png

3、生成 api 的 html 文件

（1）修改doc/source/conf.py文件，在其中加入，下面的路径是根据conf 与src的相对路径决定的，如果是按照上面的文件结构，不需要修改下面代码：

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

（2）在doc目录下面，执行：

sphinx-apidoc -o ./source ../src/

sphinx-apidoc的使用，大致：

sphinx-apidoc [OPTIONS] -o   [EXCLUDE_PATTERN, …]

OUTPUT_PATH：source 文件
MODULE_PATH：python 源文件
（3）执行 html 文件清理

make clean

（4）生成 html 文件

make html

说明：这里官方文档使用的是sphinx-build -b html sourcedir builddir，但是会生成文件在 src 下面，建议使用sphinx-apidoc

image.png

（5）html 结果文件
运行上面的命令后，打开doc/build/html/index.html。

image.png

生成该网页。