sphinx doctest的真實世界使用或意義是什麼？

Question

獅身人面像中doctest的意義是什麼？有人可以通過一個簡單的例子來幫助我理解它的用法。

Answer 1

我沒有用它自己，但它是我的理解，它擴展的doctest功能。例如，它添加了testsetup和testcleanup指令，您可以將其設置和拆卸邏輯放入其中。使Sphinx可以在文檔中排除該指令。

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

Sphinx的doctest測試文檔本身。換句話說，它允許自動驗證文檔的示例代碼。雖然它也可能驗證Python代碼是否按預期工作，但Sphinx不僅僅是用於此目的（您可以更輕鬆地使用標準庫的doctest模塊）。因此，一個真實世界的場景（我經常遇到這種場景）就像這樣：一個新功能即將完成，因此我編寫了一些文檔來介紹這個新功能。新文檔包含一個或多個代碼示例。在發佈文檔之前，我在我的Sphinx文檔目錄中運行make doctest，以驗證我爲受衆撰寫的代碼示例是否真的有效。