Python之文档测试

0 参考文档

Sphinx——自动生成Python文档
Python之文档测试模块——doctest

1 doctest

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

1.1 doctest嵌入源码中

这个例子展示如何在源码中嵌入doctest用例。

• ‘>>>’ 开头的行就是doctest测试用例。
• 不带 ‘>>>’ 的行就是测试用例的输出。如果实际运行的结果与期望的结果不一致，就标记为测试失败。

有两个地方可以放doctest测试用例，一个位置是模块的最开头，另一个位置是函数声明语句的下一行（就像上面的例子这样）。除此之外的其它地方不能放，放了也不会执行。

verbose参数，如果设置为True则在执行测试的时候会输出详细信息。默认是False，表示运行测试时，只有失败的用例会输出详细信息，成功的测试用例不会输出任何信息。

def multiply(a, b):
    """
    >>> multiply(4, 3)
    12
    >>> multiply('a', 3)
    'aaa'
    """
    return a * b
if __name__=='__main__':
    import doctest
    doctest.testmod(verbose=True)

上面启动测试的方式是在__main__函数中调用了doctest.testmod()方法。

如果__main__函数有其他用途，不方便调用doctest.testmod()方法，那么可以用另外一种执行测试的方法，在cmd中输入：

python -m doctest xxx.py 
python -m doctest -v xxx.py

上面，-m 表示引用一个模块，-v 等价于 verbose=True。运行输出与上面基本一样。

1.2 doctest放到独立文件中

如果不想将doctest测试用例嵌入到python的源码中，则可以建立一个独立的文本文件来保存测试用例。

将xxx.py中的doctest内容拷贝出来放到sasuke.txt文件里，注意sasuke.txt也要放在与naruto.py相同的目录中。

下面是sasuke.txt的内容：

>>> from naruto import multiply
>>> multiply(4, 3)
12
>>> multiply('a', 3)
'aaa'

注意：from 那一行也要以>>>开头。

打开cmd（使用命令d:切换到该目录），输入：

python -m doctest -v sasuke.txt

输出为：

Trying:
    from xxx import multiply
Expecting nothing
ok
Trying:
    multiply(4, 3)
Expecting:
    12
ok
Trying:
    multiply('a', 3)
Expecting:
    'aaa'
ok
1 items passed all tests:
   3 tests in sasuke.txt
3 tests in 1 items.
3 passed and 0 failed.
Test passed.

2 使用Sphinx自动生成python项目说明文档

2.1 安装Sphinx

pip install Sphinx

2.2 生成配置文件

进入项目根目录，创建doc文件夹，生成配置文件：

mkdir doc
cd doc
sphinx-quickstart

然后回答下面的问题就可以了。

> Separate source and build directories (y/n) [n]: y

> Project name: 
> Author name(s): 

> Project version []: 

> Project language [en]: 

2.3 修改配置文件

安装sphinx主题美化文档：

pip install sphinx_rtd_theme

修改doc/source/conf.py文件：

import os
import sys
# 添加源码路径
sys.path.append(os.path.join(os.path.abspath(__file__), '../../')

# 添加sphinx自动生成脚本
extensions = ['sphinx.ext.autodoc']

# 更改sphinx主题（美观一些）
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

设置自动生成文档，将conf.py中的extensions=[]改为extensions = ['sphinx.ext.autodoc',]

2.3 生成rst文件

根据配置文件与源码，生成rst文件：

sphinx-apidoc -o source ../

'source'是指的保存rst文件的路径， 你的index.rst在哪个目录，那你就指定哪个目录，当然也可以设置为其他的，也是使用相对路径。'../'就是我们要生成的html说明文档的项目路径。

index.rst这个文件指定要生成哪些文档。比如我有一个Python文件module.py在./MyPythonProject 目录下面，便可以在…toctree:: 那三行后面加上

.. automodule:: module
   :members:
   :undoc-members:

其中:members表示有注释的成员，:undoc-members表示未注释的成员（也可以加进文档里凑数，就是没有具体的说明，只有代码里的声明）。这个automodule会递归遍历module.py里面的类、成员、函数等。

注意到可能__init__ 方法中的注释会被忽略，因此需要在conf.py里面加上autoclass_content = 'both'。

2.4 代码注释编写

同时，在Python代码中的注释也要按照rst的基本法来写，不能随心所欲，否则可能会报错。常用的也就是Pycharm自动生成的:param什么的，注意对于某个函数的注释，可以是

def function(a, b):
	"""
	Some description
	
	:param a: the first argument
	:param b: the seconde argument
	
	Some other description
	"""

:param 的列表前后都需要有空格。

2.5 编译文档

执行make html,生成html文件，html的位置为：doc/build/html/index.html，用浏览器打开后是如下这样的：