sphinx.ext.doctest -- ドキュメント内の簡易テスト

It is often helpful to include snippets of code in your documentation and demonstrate the results of executing them. But it is important to ensure that the documentation stays up-to-date with the code.

This extension allows you to test such code snippets in the documentation in a natural way. If you mark the code blocks as shown here, the doctest builder will collect them and run them as doctest tests.

Within each document, you can assign each snippet to a group. Each group consists of:

  • ゼロ個以上のセットアップコードブロック。テストに必要なモジュールをimportします。

  • ひとつ以上のテストブロック。



  • Pythonコード(含プロンプト)と出力が交互に書かれている、インタラクティブモードに似たdoctestスタイルのブロック

  • 通常のPythonコードと、出力を1つから構成される、コード-出力スタイルのブロック


グループ引数は以下のように解釈されます: もしも何も指定されなかった場合には、defaultというグループ名が指定されたとみなします。もしも*が指定されると、そのブロックはdefaultを含む、すべてのグループに対して割り当てられたものとみなします。そうでなければ、これ以外の場合はグループ名は、カンマ区切りのリストでなければなりません。

.. testsetup:: [group]


.. testcleanup:: [group]


バージョン 1.1 で追加.

.. doctest:: [group]

A doctest-style code block. You can use standard doctest flags for controlling how actual output is compared with what you give as output. The default set of flags is specified by the doctest_default_flags configuration variable.

This directive supports five options:

  • hideはフラグオプションです。他のビルダーの使用時に、doctestブロックを隠します。デフォルトでは、ハイライトされたdoctestブロックとして表示されます。

  • optionsは文字列オプションです。それぞれのテストのサンプルに対して、カンマ区切りのdoctestフラグのリストを設定するのに使用します。doctestコメントの中でサンプルごとにフラグを明示することもできますが、他のビルダーをしようすると、そのフラグまでレンダリングされてしまいます。

  • pyversion, a string option, can be used to specify the required Python version for the example to be tested. For instance, in the following case the example will be tested only for Python versions greater than 3.3:

    .. doctest::
       :pyversion: > 3.3

    The following operands are supported:

    • ~=: Compatible release clause

    • ==: Version matching clause

    • !=: Version exclusion clause

    • <=, >=: Inclusive ordered comparison clause

    • <, >: Exclusive ordered comparison clause

    • ===: Arbitrary equality clause.

    pyversion option is followed PEP-440: Version Specifiers.

    バージョン 1.6 で追加.

    バージョン 1.7 で変更: Supported PEP-440 operands and notations

  • trim-doctest-flags and no-trim-doctest-flags, a flag option, doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers are removed (or not removed) individually. Default is trim-doctest-flags.



>>> datetime.date.now()   # doctest: +SKIP
datetime.date(2008, 1, 1)


.. testcode:: [group]


This directive supports three options:

  • hideはフラグオプションです。他のビルダーの使用時に、codeブロックを隠します。デフォルトでは、ハイライトされたcodeブロックとして表示されます。

  • trim-doctest-flags and no-trim-doctest-flags, a flag option, doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers are removed (or not removed) individually. Default is trim-doctest-flags.


testcode ブロックの中のコードは、含まれている文の量に関わらず、すべて、一度だけ実行されます。そのため、単なる式の場合には、出力は 行われませんprint を使用してください。サンプル:

.. testcode::

   1+1         # this will give no output!
   print(2+2)  # this will give output

.. testoutput::



.. testoutput:: [group]

最後に定義された testcode ブロックに対応する出力, もしくは例外メッセージを定義します。

This directive supports four options:

  • hideはフラグオプションです。他のビルダーの使用時に、ブロックを隠します。デフォルトでは、ハイライトせずにリテラルブロックとして表示されます。

  • optionsは文字列オプションで、通常のdoctestブロックと同じように、カンマ区切りのdoctestのフラグを設定するのに使用されます。

  • trim-doctest-flags and no-trim-doctest-flags, a flag option, doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers are removed (or not removed) individually. Default is trim-doctest-flags.


.. testcode::

   print('Output     text.')

.. testoutput::

   Output text.

以下のコードはこれらのディレクティブの使用方法のサンプルです。 doctest を使用したテストと、 testcode および testoutput の二つで構成されたテストは等価です.

The parrot module

.. testsetup:: *

   import parrot

The parrot module is a module about parrots.

Doctest example:

.. doctest::

   >>> parrot.voom(3000)
   This parrot wouldn't voom if you put 3000 volts through it!

Test-Output example:

.. testcode::


This would output:

.. testoutput::

   This parrot wouldn't voom if you put 3000 volts through it!

Skipping tests conditionally

skipif, a string option, can be used to skip directives conditionally. This may be useful e.g. when a different set of tests should be run depending on the environment (hardware, network/VPN, optional dependencies or different versions of dependencies). The skipif option is supported by all of the doctest directives. Below are typical use cases for skipif when used for different directives:

  • testsetup and testcleanup

    • conditionally skip test setup and/or cleanup

    • customize setup/cleanup code per environment

  • doctest

    • conditionally skip both a test and its output verification

  • testcode

    • conditionally skip a test

    • customize test code per environment

  • testoutput

    • conditionally skip output assertion for a skipped test

    • expect different output depending on the environment

The value of the skipif option is evaluated as a Python expression. If the result is a true value, the directive is omitted from the test run just as if it wasn't present in the file at all.

Instead of repeating an expression, the doctest_global_setup configuration option can be used to assign it to a variable which can then be used instead.

Here's an example which skips some tests if Pandas is not installed:

extensions = ['sphinx.ext.doctest']
doctest_global_setup = '''
    import pandas as pd
except ImportError:
    pd = None
.. testsetup::
   :skipif: pd is None

   data = pd.Series([42])

.. doctest::
   :skipif: pd is None

   >>> data.iloc[0]

.. testcode::
   :skipif: pd is None


.. testoutput::
   :skipif: pd is None



The doctest extension uses the following configuration values:


By default, these options are enabled:

  • ELLIPSIS, allowing you to put ellipses in the expected output that match anything in the actual output;

  • IGNORE_EXCEPTION_DETAIL, causing everything following the leftmost colon and any module information in the exception name to be ignored;

  • DONT_ACCEPT_TRUE_FOR_1, rejecting "True" in the output where "1" is given -- the default behavior of accepting this substitution is a relic of pre-Python 2.2 times.

バージョン 1.5 で追加.


doctestビルダーが使用されるときに、 sys.path に対して追加されるディレクトリのリストです。必ず絶対パスで記述してください。



バージョン 0.6 で追加.


すべてのテストグループがテストを終了したあとに呼ばれる、 testcleanup ディレクティブを、すべてのファイルに作ります。この設定にはPythonのコードを書きます。すべてのテンポラリファイルを削除などの使い方ができます。

バージョン 1.1 で追加.




Some documentation text.

>>> print(1)

Some more documentation text.



Some documentation text.

.. doctest::

   >>> print(1)

Some more documentation text.

この機能があるおかげで autodoc 拡張を使用して取り込んだdocstring中のdoctestを簡単に実行できます。特別なディレクティブでマークアップする必要はありません。

しかし、 reST doctest ブロックには空行を含めることができないということに注意してください。それらは一つのブロックの終わりと別のブロックの開始として解釈されるでしょう。また <BLANKLINE># doctest: オプションの除去は doctest ブロックの中でのみ機能します。ただし、 trim_doctest_flags を設定して、 Python コンソールの内容を含むすべてのコードブロックでもそれを実現できます。