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 doctestdoctest.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]:  zh_CN

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 argumentSome other description"""

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

2.5 编译文档

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

Python之文档测试相关推荐

python/单元测试-文档测试
文章目录单元测试 __setattr__ 运行单元测试: setUp与tearDown 练习:对Student类编写单元测试,结果发现测试不通过,请修改Student类,让测试通过: 文档测试单元 ...
python测试开发教程_文档测试
如果你经常阅读Python的官方文档,可以看到很多文档都有示例代码.比如re模块就带了很多示例代码: >>> import re >>> m = re.search ...
python 错误、调试、单元测试、文档测试
错误分为程序的错误和由用户错误的输入引起的错误,此外还有因为各种各样意外的情况导致的错误,比如在磁盘满的时候写入.从网络爬取东西的时候,网络断了.这类错误称为异常错误处理普通的错误处理机制就是在出 ...
Python单元测试、Python文档测试
Python语言基础(单元测试–对函数进行测试)(熟练) 概述: 单元测试: 用来对一个函数,一个类或者一个模块来进行一个正确性的校验工作结果: 1.单元测试通过:说明测试的函数功能正常 2.单元测 ...
python文档测试_【Python入门】19.调试器pdb、单元测试unittest和文档测试doctest
笔记更新于2019年12月4日, 摘要:各种调试方法介绍assert.logging.调试器pdb:单元测试unittest的编写方法.如何运行单元测试:文档测试doctest的编写写在前面:为了更 ...
python学习-测试（文档测试 doctest、单元测试 unittest）
文章目录文档测试单元测试文档测试 doctest:一个简单的模块,为检查文档而设计,但也适合用来编写单元测试. def func(a, b):"""doc test ...
python 帮助文档、自我解释
现在让我们以交互方式使用 Python 来开始研究.当我们从命令行启动 Python 时,就进入了 Python shell,在这里可以输入 Python 代码,而且立刻会从 Python 解释器获得 ...
关于深度学习框架Hamaa与Python API文档生成工具Sophon
五月两场 | NVIDIA DLI 深度学习入门课程 5月19日/5月26日一天密集式学习快速带你入门阅读全文> 正文共1988个字,预计阅读时间12分钟. 前言最近三个月我主要花时间在造 ...
python生成接口文档_使用apiDoc实现python接口文档编写
使用apiDoc实现python接口文档编写 apiDoc的安装 npm install apidoc -g 生成api的终端命令:apidoc -i 代码所在路径-o 生成文件的路径接口文档的编写 ...

Python之文档测试