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します。
ひとつ以上のテストブロック。
doctest
ビルダーを使用してドキュメントをビルドすると、それぞれのドキュメントごとに同一グループの要素が集められて次々に実行されます。最初はセットアップコードブロックが実行され、その後はファイルの中で登場する順番にテストブロックが実行されます。
テストブロックには以下の2種類あります:
Pythonコード(含プロンプト)と出力が交互に書かれている、インタラクティブモードに似たdoctestスタイルのブロック
通常のPythonコードと、出力を1つから構成される、コード-出力スタイルのブロック
ディレクティブ¶
グループ引数は以下のように解釈されます: もしも何も指定されなかった場合には、default
というグループ名が指定されたとみなします。もしも*
が指定されると、そのブロックはdefault
を含む、すべてのグループに対して割り当てられたものとみなします。そうでなければ、これ以外の場合はグループ名は、カンマ区切りのリストでなければなりません。
- .. testsetup:: [group]¶
セットアップのためのコードブロックです。このコードは他のビルダーを使用したときには出力されませんが、それが所属するグループのdoctestが実行される前に実行されます。
オプション
- :skipif: condition (text)¶
Skip the directive if the python expression condition is True. See skipping tests conditionally.
- .. testcleanup:: [group]¶
片付けをするためのコードブロックです。このコードは他のビルダーを使用したときには出力されませんが、それが所属するグループのdoctestが実行された後に実行されます。
Added in version 1.1.
オプション
- :skipif: condition (text)¶
Skip the directive if the python expression condition is True. See skipping tests conditionally.
- .. 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 thedoctest_default_flags
configuration variable.オプション
- :hide:¶
Hide the doctest block in other builders. By default it is shown as a highlighted doctest block.
- :options: doctest flags (comma separated list)¶
A comma-separated list of doctest flags that apply to each example in the tests. (You still can give explicit flags per example, with doctest comments, but they will show up in other builders too.)
Alternatively, you can give inline doctest options, like in doctest:
>>> datetime.date.now() datetime.date(2008, 1, 1)
They will be respected when the test is run, but by default will be stripped from presentation output. You can prevent stripping using the option
doctest:no-trim-doctest-flags
.
- :pyversion: (text)¶
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.12:
.. doctest:: :pyversion: > 3.12
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.Added in version 1.6.
バージョン 1.7 で変更: Supported PEP-440 operands and notations
- :trim-doctest-flags:¶
- :no-trim-doctest-flags:¶
Whether to trim remove doctest flags (comments looking like
# doctest: FLAG, ...
) at the ends of lines and<BLANKLINE>
markers individually. Default istrim-doctest-flags
.標準ライブラリのdoctestでは、予想出力の中に空行を入れたい場合には
<BLANKLINE>
というキーワードを指定しなければなりませんでした。<BLANKLINE>
はHTMLやLaTeXなど、人が読める出力を行うビルドの際には削除されます。
- :skipif: condition (text)¶
Skip the directive if the python expression condition is True. See skipping tests conditionally.
- .. testcode:: [group]¶
コード-出力タイプのテストのコードブロックです。
オプション
- :hide:¶
Hide the code block in other builders. By default it is shown as a highlighted code block.
- :trim-doctest-flags:¶
- :no-trim-doctest-flags:¶
Whether to trim remove doctest flags (comments looking like
# doctest: FLAG, ...
) at the ends of lines and<BLANKLINE>
markers individually. Default istrim-doctest-flags
.
- :skipif: condition (text)¶
Skip the directive if the python expression condition is True. See skipping tests conditionally.
注釈
testcode
ブロックの中のコードは、含まれている文の量に関わらず、すべて、一度だけ実行されます。そのため、単なる式の場合には、出力は 行われません 。print
を使用してください。サンプル:.. testcode:: 1+1 # this will give no output! print(2+2) # this will give output .. testoutput:: 4
doctestモジュールも、通常の出力と、例外メッセージを同じコードスニペット内で混ぜた書き方をサポートしていないように、testcode/testoutputにも同様の制限がある点に注意してください。
- .. testoutput:: [group]¶
最後に定義された
testcode
ブロックに対応する出力, もしくは例外メッセージを定義します。- :hide:¶
Hide the doctest block in other builders. By default it is shown as a highlighted doctest block.
- :options: doctest flags (comma separated list)¶
A comma-separated list of doctest flags.
- :trim-doctest-flags:¶
- :no-trim-doctest-flags:¶
Whether to trim remove doctest flags (comments looking like
# doctest: FLAG, ...
) at the ends of lines and<BLANKLINE>
markers individually. Default istrim-doctest-flags
.
- :skipif: condition (text)¶
Skip the directive if the python expression condition is True. See skipping tests conditionally.
サンプル:
.. testcode:: print('Output text.') .. testoutput:: :hide: :options: -ELLIPSIS, +NORMALIZE_WHITESPACE 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::
parrot.voom(3000)
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
andtestcleanup
conditionally skip test setup and/or cleanup
customize setup/cleanup code per environment
-
conditionally skip both a test and its output verification
-
conditionally skip a test
customize test code per environment
-
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 = '''
try:
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]
42
.. testcode::
:skipif: pd is None
print(data.iloc[-1])
.. testoutput::
:skipif: pd is None
42
設定¶
The doctest extension uses the following configuration values:
- doctest_default_flags¶
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.
Added in version 1.5.
- doctest_show_successes¶
Defaults to
True
. Controls whether successes are reported.For a project with many doctests, it may be useful to set this to
False
to only highlight failures.Added in version 7.2.
- doctest_global_setup¶
Pythonコードを記述します。このコードはテストされるすべてのファイルの
testsetup
ディレクティブに書き込んだのと同じように扱われます。例えば、doctest時にいつでも必要となるモジュールをimportするといった用途に使用できます。Added in version 0.6.
- doctest_global_cleanup¶
すべてのテストグループがテストを終了したあとに呼ばれる、
testcleanup
ディレクティブを、すべてのファイルに作ります。この設定にはPythonのコードを書きます。すべてのテンポラリファイルを削除などの使い方ができます。Added in version 1.1.
- doctest_test_doctest_blocks¶
If this is a nonempty string (the default is
'default'
), standard reStructuredText doctest blocks will be tested too. They will be assigned to the group name given.reStructuredText doctest blocks are simply doctests put into a paragraph of their own, like so:
Some documentation text. >>> print(1) 1 Some more documentation text.
reSTの場合は、doctestブロックを表現するのに特別な
::
は使用されません。docutilsは>>>
から始まる行を識別します。そのため、doctestのために追加でインデントを設定する必要はありません。この設定値がデフォルトのままであったとすると、上記のコード片は、下記のように書いた場合と同じようにdoctestビルダーから解釈されます:
Some documentation text. .. doctest:: >>> print(1) 1 Some more documentation text.
この機能があるおかげで
autodoc
拡張を使用して取り込んだdocstring中のdoctestを簡単に実行できます。特別なディレクティブでマークアップする必要はありません。Note though that you can't have blank lines in reStructuredText doctest blocks. They will be interpreted as one block ending and another one starting. Also, removal of
<BLANKLINE>
and# doctest:
options only works indoctest
blocks, though you may settrim_doctest_flags
to achieve that in all code blocks with Python console content.