Question

什么是doctest在Sphinx中的意义？有人可以通过一个简单的例子来帮助我理解它的使用。

Answer 1

Sphinx的doctest用于测试文档本身。换句话说，它允许自动验证文档的示例代码。虽然它也可以验证Python代码是否按预期工作，但仅仅为此目的不需要Sphinx（您可以更轻松地使用标准库的doctest模块）。

所以，一个真实的场景（我经常发现自己的场景）是这样的：一个新功能即将完成，所以我写了一些文档来介绍新功能。新文档包含一个或多个代码示例。在发布文档之前，我在我的Sphinx文档目录中运行make doctest以验证我为受众编写的代码示例是否真的有用。

Answer 2

这是一个简单的例子（来自the doctest module）：

"""
This is the "example" module.

The example module supplies one function, factorial().  For example,

>>> factorial(5)
120
"""

def factorial(n):
    """Return the factorial of n, an exact integer >= 0.

    If the result is small enough to fit in an int, return an int.
    Else return a long.

    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> [factorial(long(n)) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> factorial(30)
    265252859812191058636308480000000L
    >>> factorial(30L)
    265252859812191058636308480000000L
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n must be >= 0

    Factorials of floats are OK, but the float must be an exact integer:
    >>> factorial(30.1)
    Traceback (most recent call last):
        ...
    ValueError: n must be exact integer
    >>> factorial(30.0)
    265252859812191058636308480000000L

    It must also not be ridiculously large:
    >>> factorial(1e100)
    Traceback (most recent call last):
        ...
    OverflowError: n too large
    """

    import math
    if not n >= 0:
        raise ValueError("n must be >= 0")
    if math.floor(n) != n:
        raise ValueError("n must be exact integer")
    if n+1 == n:  # catch a value like 1e300
        raise OverflowError("n too large")
    result = 1
    factor = 2
    while factor <= n:
        result *= factor
        factor += 1
    return result


if __name__ == "__main__":
    import doctest
    doctest.testmod()

Answer 3

我自己没有使用它，但我的理解是它扩展了doctest的功能。例如，它添加了testsetup和testcleanup指令，您可以将设置和拆卸逻辑放入其中。使Sphinx可以在文档中排除它。

什么是sphinx doctest的真实世界用途或意义？

3 个答案: