使用sphinx自动建立API文档(一)

1、使用 demo 的 python 文件

建立test_demo为根目录,下面分别建立docsrc文件夹。

使用sphinx自动建立API文档(一)_第1张图片
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 文件

cddoc目录下。
输入命令: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

使用sphinx自动建立API文档(一)_第2张图片
image.png

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

生成的文件结构如下:


使用sphinx自动建立API文档(一)_第3张图片
image.png

3、生成 api 的 html 文件

(1)修改doc/source/conf.py文件,在其中加入,下面的路径是根据confsrc的相对路径决定的,如果是按照上面的文件结构,不需要修改下面代码:

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

使用sphinx自动建立API文档(一)_第4张图片
image.png

生成该网页。

你可能感兴趣的