使用doctest代码测试和Sphinx自动生成文档

python代码测试并自动生成文档

Tips：两大工具：doctest–单元测试、Sphinx–自动生成文档

1.doctest

doctest是python自带的一个模块。doctest有两种使用方式：一种是嵌入到python源码中，另外一种是放到一个独立文件。

1.1 嵌入源码

新建test.py

import doctest
'''
'>>>' 开头的行就是doctest测试用例。
不带 '>>>' 的行就是测试用例的输出。
如果实际运行的结果与期望的结果不一致，就标记为测试失败。
'''
def multiply(a, b):
    """
    >>> multiply(3, 2)
    6
    >>> multiply('a', 3)
    'aaa'
    """
    return a * b
if __name__=='__main__':
    doctest.testmod(verbose=True) 
    # verbose=True即强制使用详细模式:不管执行如何均输出详细信息，
    # 若verbose=False则只输出测试结果不符合的信息

执行结果为：

Trying:
    multiply(3, 2)
Expecting:
    6
ok
Trying:
    multiply('a', 3)
Expecting:
    'aaa'
ok
1 items had no tests:
    __main__
1 items passed all tests:
   2 tests in __main__.multiply
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

如果__main__函数有其他用途，不方便调用doctest.testmod()方法，那么可以用另外一种执行测试的方法，在cmd中输入：python -m doctest test.py或者python -m doctest -v test.py。
其中-m表示引用一个模块，-v等价于verbose=True。运行输出与上面基本一样。

1.2 独立使用

新建一个save.txt文件来保存测试用例。
将test.py中的doctest内容拷贝出来放到save.txt文件里，注意save.txt要放在与test.py相同的目录中

下面是save.txt的内容：

>>> from test import multiply
>>> multiply(3, 2)
6
>>> multiply('a', 3)
'aaa'

打开cmd，切换到py文件路径，输入python -m doctest save.txt或者python -m doctest -v save.txt
可以得到和1.1节中相同的输出结果。

Tips：个人建议使用1.2节中的方法。

2.Sphinx

首先，python不自带Sphinx，需要用pip install sphinx安装(anaconda已经预装)
新建项目sphinx_demo，sphinx_demo/src放项目代码test.py，sphinx_demo/doc放sphinx最终自动生成的文档

2.1 reStructuredText风格

reStructuredText风格是pycharm默认注释风格

# -*- coding: utf-8 -*-
class divide_class:
    '''reStructuredText风格：用冒号分隔，PyCharm默认风格

    :arg dividend: 被除数

    :type dividend: int

    '''
 
    def __init__(self, dividend, name='ReStructuredTextStyle'):
        self.dividend = dividend
        self.name = name
 
    def divide(self, divisor):
        '''除法

        reStructuredText风格的函数，类型主要有param、type、return、rtype、exception

        :param divisor: 除数

        :type divisor: int

        :returns: 除法结果

        :rtype: :obj:`int` or :obj:`str`

        :exception TypeError: the type of divisor isn't int

        >>> reStructredText = ReStructuredTextStyle(dividend=10)
        >>> reStructredText.divide(5)
        2

        '''
        try:
            if isinstance(divisor, int):
                return self.dividend / divisor
            else:
                raise TypeError("Error!The type of divisor isn't int!")
        except TypeError as e:
            return e

2.2 Google

Google注释风格是影响力最大的一个，而且十分简洁。

# -*- coding: utf-8 -*-

class divide_class:
    '''Google注释风格:用 ``缩进`` 分隔，适用于倾向水平，短而简单的文档

    Attributes:
        dividend (int or float): 被除数

    '''
 
    def __init__(self, dividend):
        self.dividend = dividend
 
    def divide(self, divisor):
        '''除法
        Google注释风格的函数，类型主要有Args、Returns、Raises、Examples

        Args:
            divisor (int):除数

        Returns:
            除法结果

        Raises:
            ZeroDivisionError: division by zero

        Examples:
            >>> google = GoogleStyle(divisor=10)
            >>> google.divide(5)
            2

        References:
            除法_百度百科  https://baike.baidu.com/item/%E9%99%A4%E6%B3%95/6280598
        
        '''
        try:
            return self.dividend / divisor
        except ZeroDivisionError as e:
            return e

在命令行cd到sphinx_demo/doc，执行命令sphinx-quickstart，设置结构分离、项目名、作者名、版本号、语言

> Separate source and build directories (y/n) [n]: y
> Project name: sphinx_demo
> Author name(s): XerCis
> Project release []: 1.0
> Project language [en]: zh_CN 或 回车默认英文

在doc/source/conf.py指定项目代码路径sphinx_demo/src,并修改扩展extensions

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

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

执行生成API文档命令sphinx-apidoc -o source ../src/,再用make html(linux)或者.\make html(windows)生成网页文件,打开doc/build/html/index.html即可看到文档