Каково реальное использование или значение sphinx doctest? - PullRequest
Новая
       10

Каково реальное использование или значение sphinx doctest?

1 голос
/ 17 ноября 2011

Какое значение имеет doctest в сфинксе?Может кто-нибудь помочь мне понять его использование на простом примере.

Ответы [ 3 ]

3 голосов
/ 14 августа 2013

Документ Sphinx предназначен для тестирования самой документации.Другими словами, он позволяет автоматически проверять образец кода в документации.Хотя он также может проверять, работает ли код Python должным образом, Sphinx не нужен только для этой цели (вы могли бы проще использовать модуль doctest стандартной библиотеки).

Итак, сценарий реального мира (одинЯ нахожусь на регулярной основе) происходит примерно так: новая функция близка к завершению, поэтому я пишу некоторую документацию, чтобы представить новую функцию.Новые документы содержат один или несколько примеров кода.Перед публикацией документации я запускаю make doctest в своем каталоге документации Sphinx, чтобы убедиться, что примеры кода, которые я написал для аудитории, действительно будут работать.

1 голос
/ 11 августа 2013

Я не использовал его сам, но, насколько я понимаю, он расширяет функциональность doctest. Например, он добавляет директивы testsetup и testcleanup, в которые вы можете поместить свою логику настройки и разрыва. Это позволяет Sphinx исключить это из документации.

1 голос
/ 17 ноября 2011

Вот простой пример (из модуль doctest ): 

"""
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()
...