Автоматически генерировать вывод doctest с расширением Sphinx

Question

Мне кажется, что-то не хватает в расширении sphinx для doctest.

Типичный пример в документации:

.. doctest::

   >>> print 1
   1

Разве нет способа позволить sphinx автоматически генерировать вывод (здесь: 1)?

Насколько я понял, можно запустить:

$ make doctest

, который позволяет протестировать фрагменты кода и сравнить реальный результат с ожидаемым. Например, если у вас есть

.. doctest::

   >>> print 1
   3

doctest предупредит вас, что получил 1 в то время как ожидал 3.

Вместо этого я бы хотел, чтобы sphinx вставлял реальный вывод один в мою строку документации или в мой файл .rst. Например, если у нас есть что-то вроде:

.. doctest::

    >>> print 1
    >>> print [2*x for x in range(3)]

Мне бы хотелось, чтобы, когда мы запускаем make doctest с параметром, он изменял строку документации на:

.. doctest::

   >>> print 1
   1
   >>> print [2*x for x in range(3)]
   [0,2,4]

Я уверен, что это возможно, и было бы очень удобно!

Answer 1

Я должен настоятельно (но любезно) посоветовать против того, что вы пытаетесь сделать.

То, что вы спрашиваете, против "тестовой части" модуль doctest :

Модуль doctest ищет фрагменты текста, которые выглядят как интерактивные сеансы Python, а затем выполняет эти сеансы, чтобы убедиться, что они работают точно так, как показано.

У этих тестов есть причины: вы записываете ввод и ожидаемый вывод и позволяете Python проверять, соответствует ли ожидаемый вывод фактическому выводу.

Если вы разрешите Python производитьожидаемый результат, ну .. он больше не будет ожидаемым (пользователем / автором), поэтому doctests никогда не потерпит неудачу, поэтому эти тесты будут бесполезны.

Примечание: Если внутри функции нет логики (if / else, while-loop, добавления и т. Д.), Нет необходимости проверять их.И тесты не должны воспроизводить логику тестирования, иначе они больше не тестируют функцию.

Мне показалось это видео о разработке через тестирование, очень интересной, может быть, она может быть вам интереснаесли вы хотите узнать больше об этом аргументе.

Answer 2

Вот предложение о том, как вы могли бы достичь того, чего, я подозреваю, вы ищете:

Даг Хеллманн написал интересную статью под названием Написание технической документации с помощью Sphinx, Paver и Cog . В нем есть раздел , описывающий, как инструмент Cog может использоваться для автоматического запуска примеров кода и записи выходных данных для включения в документацию, созданную Sphinx.

---

Существует также расширение Sphinx, называемое autorun , которое может выполнять код в специальном runblock и приложите вывод к документации.