`sphinx.ext.doctest` --文書内のテストコードセグメント¶

文書にコード片が含まれており、それらを実行する結果を提示することは、一般に有用である。しかし、文書とコードが最新に維持されることを確実にすることが重要だ。

この拡張により、このようなコード片を自然な方法で文書でテストすることができます。以下のようにコードブロックをマークすると doctest Builderはそれらを収集し，doctestテストとして動作する.

各文書において、各コードセグメントを割り当てることができる 集団化する. それがそうです。各グループは以下のメンバーで構成されている。

ゼロ以上です コードを設定する ブロック(たとえば，テストするモジュールを導入)
1つまたは複数 test 積み木

使用している doctest 生成器では，文書収集グループごとに次々と実行され，まず実装コードブロックを実行し，テストブロックがファイルに出現する順にテストブロックを実行する.

テストブロックには2種類あります

doctest-style ブロックは、インターレースPythonコード(インタプリタプロンプトを含む)と出力によって対話型セッションをシミュレートします。
code-output-style ブロックは通常のPythonコードからなり，そのコードの出力からなるセグメントを選択することもできる.

指令¶

♪the 集団化する. 以下のパラメータは以下のように解釈される：このパラメータが空であれば，そのブロックを名前に割り当てる. default それがそうです。もしそうなら * ブロックは、すべてのグループに割り当てられる(含む) default グループ)。そうでなければ、コンマで区切られたグループ名リストでなければならない。

.. testsetup:: [group]¶: コードブロックを設定します。このコードは他のビルダの出力には表示されないが，その所属グループのdoctestの前に実行される.

.. testcleanup:: [group]¶: コードブロックをクリアします。このコードは他のビルダの出力には表示されないが，その所属グループのdoctestの後に実行される.

バージョン 1.1 で追加.

.. doctest:: [group]¶

Doctestスタイルのコードブロック。標準的なものをご利用いただけます doctest 実際の出力が提供された出力とどのように比較されるかを制御するためのフラグ。デフォルトフラグセットは doctest_default_flags 変数を配置する。

この指示は5つのオプションをサポートします：

hide 1つのフラグオプションは、doctestブロックを他の生成器に隠蔽する。デフォルトでは、ハイライト表示された文書テストブロックとして表示される。
options テストの各例に適用可能なコンマ分割doctestフラグリストを与えるために使用することができる文字列オプション。(各例でdoctest注釈を使用して明示的なフラグを与えることができますが、他のビルダにも登場します。)
pyversion 文字列オプションは、テストするサンプルに必要なPythonバージョンを指定するために使用できます。例えば、以下の場合、この例は、3.3を超えるPythonバージョンについてのみテストされる：
```
.. doctest::
   :pyversion: > 3.3
```
以下のオペランドをサポートする：
- ~= ：互換バージョン条項
- == ：バージョン照合子句
- != ：バージョン除外条項
- <=, >=: Inclusive ordered comparison clause
- <, >: Exclusive ordered comparison clause
- === ：独断的な平等条項。
pyversion option is followed PEP-440: Version Specifiers それがそうです。

バージョン 1.6 で追加.

バージョン 1.7 で変更: サポートされているPEP-440オペランドとシンボル
trim-doctest-flags そして no-trim-doctest-flags 、マークオプション、doctestフラグ(注釈は以下の通り # doctest: FLAG, ... )と <BLANKLINE> タグをそれぞれ削除(または削除しない)する.デフォルト値は trim-doctest-flags それがそうです。

標準文書テストと同様に、ご利用いただく必要がありますのでご注意ください <BLANKLINE> 期待出力中の空行を表す.♪the <BLANKLINE> プレゼンテーション出力(HTML，LaTeXなど)を生成する際に削除する.

また、doctest：などのイントラネットdoctestオプションを提供することもできます。

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

これらはテスト実行時に尊重されるが，プレゼンテーション出力から削除される.

.. testcode:: [group]¶

コード出力パターンテストのためのコードブロック。

この指示は3つのオプションをサポートします：

hide フラグオプションは，他の生成器にコードブロックを隠蔽する.デフォルトでは、強調表示されたコードブロックとして表示される。
trim-doctest-flags そして no-trim-doctest-flags 、マークオプション、doctestフラグ(注釈は以下の通り # doctest: FLAG, ... )と <BLANKLINE> タグをそれぞれ削除(または削除しない)する.デフォルト値は trim-doctest-flags それがそうです。

注釈

コントロール中のコード testcode ブロックは常に一度にすべて実行され，それがいくつの文を含んでいても.したがって出力は not 純粋な表現生成のための-使用 print それがそうです。例：：

.. testcode::

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

.. testoutput::

   4

また，doctestモジュールは同一コードセグメントに通常の出力と異常メッセージを混合して使用することをサポートしていないため，testcode/testoutputにも適していることに注意されたい.

.. testoutput:: [group]¶

の対応した出力または例外メッセージ. testcode 立ちはだかっています。

この指示は4つのオプションをサポートします：

hide フラグオプションは、他の生成器に出力ブロックを隠蔽する。デフォルトの場合、文字ブロックとして表示され、強調表示されません。
options 1つの文字列オプションは、通常のdoctestブロックのようにdoctestフラグ(コンマ分離)を提供するために使用することができる。
trim-doctest-flags そして no-trim-doctest-flags 、マークオプション、doctestフラグ(注釈は以下の通り # doctest: FLAG, ... )と <BLANKLINE> タグをそれぞれ削除(または削除しない)する.デフォルト値は trim-doctest-flags それがそうです。

例：：

.. 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!

条件付きでテストをスキップする¶

skipif 文字列オプションは、命令を条件付きでスキップするために使用することができる。例えば、異なるテストのセットが、環境(ハードウェア、ネットワーク/VPN、オプション依存項、または依存項の異なるバージョン)に従って実行されるべきである場合、これは有用である可能性がある。♪the skipif オプションはすべてのdoctestコマンドによってサポートされています。以下に以下の典型的な使用状況を示す. skipif 異なる命令に使用された場合：

testsetup and testcleanup
- テスト設定および/またはクリーニングを条件付きでスキップする
- 環境定義に応じたコードの設定/クリーニング
doctest
- テストとその出力検証を条件付きでスキップする.
testcode
- 条件付きでテストをスキップする
- 環境に応じてテストコードをカスタマイズする
testoutput
- スキップされたテストの出力アサートを条件付きでスキップする
- 環境によっては異なる出力が望ましい

の値です。 skipif オプションはPython式として値を求める.結果が真値であれば，その命令はファイルにまったく存在しないようにテスト実行から省略される.

繰返し式ではなく， doctest_global_setup 構成オプションは、変数を与えるために使用されてもよく、その後、変数を使用するように変更されてもよい。

以下の例は、Pandasがインストールされていない場合にいくつかのテストをスキップする。

conf.py¶

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

contents.rst¶

.. 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

配置¶

Doctest拡張には以下の配置値を用いる：

doctest_default_flags¶

デフォルトの場合、以下のオプションが有効になります。

ELLIPSIS 実際の出力のいずれかに一致する省略番号を予期される出力に配置することができます。
IGNORE_EXCEPTION_DETAIL この結果、例外名の最も左のコロンの後のすべてのコンテンツおよび任意のモジュール情報が無視される。
DONT_ACCEPT_TRUE_FOR_1 “1”が与えられた出力で“True”を拒否する--この置換を受け入れるデフォルトアクションは、Python 2.2回よりも早い遺跡です。

バージョン 1.5 で追加.

doctest_path¶: 追加されたディレクトリリスト sys.path Doctest生成器を用いた場合。(絶対経路が含まれていることを確認してください。)

doctest_global_setup¶: Pythonコード、その処理方法とそれを入れる testsetup 以下の対象に対するコマンド 間隔を置いて テストされたファイルは、グループごとに。例えば、文書テストで常に必要なモジュールを導入するために使用することができます。

バージョン 0.6 で追加.

doctest_global_cleanup¶: Pythonコード、その処理方法とそれを入れる testcleanup 以下の対象に対するコマンド 間隔を置いて テストされたファイルは、グループごとに。例えば、テストに残された任意の一時ファイルを削除するためにそれを使用することができます。

バージョン 1.1 で追加.

doctest_test_doctest_blocks¶

これが非空文字列であれば(デフォルト値は 'default' )についても、標準REST doctestブロックをテストする。それらは与えられたグループ名に割り当てられるであろう.

REST文書テストブロックは，それら自身の段落に置かれた文書テストのみであり，以下のようになる.

Some documentation text.

>>> print(1)
1

Some more documentation text.

(特別なものはありませんのでご注意ください :: Doctestブロックを導入しますdocutilsはプリアンブルと >>> それがそうです。また、これはダメージを与えないにもかかわらず、追加的なインデントは使用されていない。)

この値をデフォルト値として保持すると、doctest構築器は、上記のコード片を完全に以下のように解釈する。

Some documentation text.

.. doctest::

   >>> print(1)
   1

Some more documentation text.

この機能により、添付されている文書文字列で文書テストを簡単にテストすることができます autodoc 特別な指示を使用してそれらをマークすることなく拡張する。

ただし，REST文書テストブロックに空きがあってはならないことに注意されたい.それらは1ブロックの終わりと別のブロックの始まりと解釈されるだろう。また，削除 <BLANKLINE> そして # doctest: オプションは適用されます doctest ブロックですが、設定することができます trim_doctest_flags これは、Pythonコンソールの内容を含むすべてのコードブロックで実現されます。

Table of Contents

前のトピックへ

次のトピックへ

`sphinx.ext.doctest` --文書内のテストコードセグメント¶

指令¶

条件付きでテストをスキップする¶

配置¶

sphinx.ext.doctest --文書内のテストコードセグメント¶

指令¶

条件付きでテストをスキップする¶

配置¶

`sphinx.ext.doctest` --文書内のテストコードセグメント¶