1击罪、使用 demo 的 python 文件

建立test_demo為根目錄锰提，下面分別建立doc和src文件夾嫂拴。

image.png

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: 這是一個(gè)參數(shù)(沒有 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: 這是一個(gè)參數(shù)(沒有 str 字符類型)
    :return: 信息
    """
    pass

2束凑、建立基本的 sphinx 文件

cd到doc目錄下。
輸入命令：sphinx-quickstart富稻，會彈出一些選項(xiàng)問題掷邦。

> 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需要設(shè)置為y耙饰。

image.png

上面設(shè)置對應(yīng)于doc/source/conf.py 中纹笼，相應(yīng)的插件纹份。

生成的文件結(jié)構(gòu)如下：

image.png

3、生成 api 的 html 文件

（1）修改doc/source/conf.py文件，在其中加入蔓涧，下面的路徑是根據(jù)conf 與src的相對路徑?jīng)Q定的件已，如果是按照上面的文件結(jié)構(gòu)，不需要修改下面代碼：

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

（2）在doc目錄下面元暴，執(zhí)行：

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

sphinx-apidoc的使用篷扩，大致：

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, …]

OUTPUT_PATH：source 文件
MODULE_PATH：python 源文件
（3）執(zhí)行 html 文件清理

make clean

（4）生成 html 文件

make html

說明：這里官方文檔使用的是sphinx-build -b html sourcedir builddir，但是會生成文件在 src 下面茉盏，建議使用sphinx-apidoc

image.png

（5）html 結(jié)果文件
運(yùn)行上面的命令后鉴未，打開doc/build/html/index.html。

image.png

生成該網(wǎng)頁鸠姨。