<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>sphinx.ext.doctest – Test snippets in the documentation — Sphinx v1.0.7 documentation</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.0.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Sphinx v1.0.7 documentation"
href="../_static/opensearch.xml"/>
<link rel="top" title="Sphinx v1.0.7 documentation" href="../index.html" />
<link rel="up" title="Sphinx Extensions" href="../extensions.html" />
<link rel="next" title="sphinx.ext.intersphinx – Link to other projects’ documentation" href="intersphinx.html" />
<link rel="prev" title="sphinx.ext.autosummary – Generate autodoc summaries" href="autosummary.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<img src="../_static/sphinx.png" alt="Sphinx logo" />
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="intersphinx.html" title="sphinx.ext.intersphinx – Link to other projects’ documentation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="autosummary.html" title="sphinx.ext.autosummary – Generate autodoc summaries"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="../extensions.html" accesskey="U">Sphinx Extensions</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="autosummary.html"
title="previous chapter"><tt class="docutils literal docutils literal docutils literal"><span class="pre">sphinx.ext.autosummary</span></tt> – Generate autodoc summaries</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="intersphinx.html"
title="next chapter"><tt class="docutils literal"><span class="pre">sphinx.ext.intersphinx</span></tt> – Link to other projects’ documentation</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/ext/doctest.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-sphinx.ext.doctest">
<span id="sphinx-ext-doctest-test-snippets-in-the-documentation"></span><h1><a class="reference internal" href="#module-sphinx.ext.doctest" title="sphinx.ext.doctest: Test snippets in the documentation."><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.doctest</span></tt></a> – Test snippets in the documentation<a class="headerlink" href="#module-sphinx.ext.doctest" title="Permalink to this headline">¶</a></h1>
<p id="index-0">This extension allows you to test snippets in the documentation in a natural
way. It works by collecting specially-marked up code blocks and running them as
doctest tests.</p>
<p>Within one document, test code is partitioned in <em>groups</em>, where each group
consists of:</p>
<ul class="simple">
<li>zero or more <em>setup code</em> blocks (e.g. importing the module to test)</li>
<li>one or more <em>test</em> blocks</li>
</ul>
<p>When building the docs with the <tt class="docutils literal"><span class="pre">doctest</span></tt> builder, groups are collected for
each document and run one after the other, first executing setup code blocks,
then the test blocks in the order they appear in the file.</p>
<p>There are two kinds of test blocks:</p>
<ul class="simple">
<li><em>doctest-style</em> blocks mimic interactive sessions by interleaving Python code
(including the interpreter prompt) and output.</li>
<li><em>code-output-style</em> blocks consist of an ordinary piece of Python code, and
optionally, a piece of output for that code.</li>
</ul>
<p>The doctest extension provides four directives. The <em>group</em> argument is
interpreted as follows: if it is empty, the block is assigned to the group named
<tt class="docutils literal"><span class="pre">default</span></tt>. If it is <tt class="docutils literal"><span class="pre">*</span></tt>, the block is assigned to all groups (including the
<tt class="docutils literal"><span class="pre">default</span></tt> group). Otherwise, it must be a comma-separated list of group
names.</p>
<dl class="directive">
<dt id="directive-testsetup">
<tt class="descname">.. testsetup::</tt><tt class="descclassname"> [group]</tt><a class="headerlink" href="#directive-testsetup" title="Permalink to this definition">¶</a></dt>
<dd><p>A setup code block. This code is not shown in the output for other builders,
but executed before the doctests of the group(s) it belongs to.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-doctest">
<tt class="descname">.. doctest::</tt><tt class="descclassname"> [group]</tt><a class="headerlink" href="#directive-doctest" title="Permalink to this definition">¶</a></dt>
<dd><p>A doctest-style code block. You can use standard <tt class="xref py py-mod docutils literal"><span class="pre">doctest</span></tt> flags for
controlling how actual output is compared with what you give as output. By
default, these options are enabled: <tt class="docutils literal"><span class="pre">ELLIPSIS</span></tt> (allowing you to put
ellipses in the expected output that match anything in the actual output),
<tt class="docutils literal"><span class="pre">IGNORE_EXCEPTION_DETAIL</span></tt> (not comparing tracebacks),
<tt class="docutils literal"><span class="pre">DONT_ACCEPT_TRUE_FOR_1</span></tt> (by default, doctest accepts “True” in the output
where “1” is given – this is a relic of pre-Python 2.2 times).</p>
<p>This directive supports two options:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">hide</span></tt>, a flag option, hides the doctest block in other builders. By
default it is shown as a highlighted doctest block.</li>
<li><tt class="docutils literal"><span class="pre">options</span></tt>, a string option, can be used to give 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.)</li>
</ul>
<p>Note that like with standard doctests, you have to use <tt class="docutils literal"><span class="pre"><BLANKLINE></span></tt> to
signal a blank line in the expected output. The <tt class="docutils literal"><span class="pre"><BLANKLINE></span></tt> is removed
when building presentation output (HTML, LaTeX etc.).</p>
<p>Also, you can give inline doctest options, like in doctest:</p>
<div class="highlight-rest"><pre>>>> datetime.date.now() # doctest: +SKIP
datetime.date(2008, 1, 1)</pre>
</div>
<p>They will be respected when the test is run, but stripped from presentation
output.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-testcode">
<tt class="descname">.. testcode::</tt><tt class="descclassname"> [group]</tt><a class="headerlink" href="#directive-testcode" title="Permalink to this definition">¶</a></dt>
<dd><p>A code block for a code-output-style test.</p>
<p>This directive supports one option:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">hide</span></tt>, a flag option, hides the code block in other builders. By
default it is shown as a highlighted code block.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Code in a <tt class="docutils literal"><span class="pre">testcode</span></tt> block is always executed all at once, no matter how
many statements it contains. Therefore, output will <em>not</em> be generated
for bare expressions – use <tt class="docutils literal"><span class="pre">print</span></tt>. Example:</p>
<div class="highlight-rest"><pre>.. testcode::
1+1 # this will give no output!
print 2+2 # this will give output
.. testoutput::
4</pre>
</div>
<p class="last">Also, please be aware that since the doctest module does not support
mixing regular output and an exception message in the same snippet, this
applies to testcode/testoutput as well.</p>
</div>
</dd></dl>
<dl class="directive">
<dt id="directive-testoutput">
<tt class="descname">.. testoutput::</tt><tt class="descclassname"> [group]</tt><a class="headerlink" href="#directive-testoutput" title="Permalink to this definition">¶</a></dt>
<dd><p>The corresponding output, or the exception message, for the last
<a class="reference internal" href="#directive-testcode" title="testcode directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">testcode</span></tt></a> block.</p>
<p>This directive supports two options:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">hide</span></tt>, a flag option, hides the output block in other builders. By
default it is shown as a literal block without highlighting.</li>
<li><tt class="docutils literal"><span class="pre">options</span></tt>, a string option, can be used to give doctest flags
(comma-separated) just like in normal doctest blocks.</li>
</ul>
<p>Example:</p>
<div class="highlight-rest"><pre>.. testcode::
print 'Output text.'
.. testoutput::
:hide:
:options: -ELLIPSIS, +NORMALIZE_WHITESPACE
Output text.</pre>
</div>
</dd></dl>
<p>The following is an example for the usage of the directives. The test via
<a class="reference internal" href="#directive-doctest" title="doctest directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">doctest</span></tt></a> and the test via <a class="reference internal" href="#directive-testcode" title="testcode directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">testcode</span></tt></a> and <a class="reference internal" href="#directive-testoutput" title="testoutput directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">testoutput</span></tt></a> are
equivalent.</p>
<div class="highlight-rest"><pre>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!</pre>
</div>
<p>There are also these config values for customizing the doctest extension:</p>
<dl class="confval">
<dt id="confval-doctest_path">
<tt class="descname">doctest_path</tt><a class="headerlink" href="#confval-doctest_path" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of directories that will be added to <tt class="xref py py-data docutils literal"><span class="pre">sys.path</span></tt> when the doctest
builder is used. (Make sure it contains absolute paths.)</p>
</dd></dl>
<dl class="confval">
<dt id="confval-doctest_global_setup">
<tt class="descname">doctest_global_setup</tt><a class="headerlink" href="#confval-doctest_global_setup" title="Permalink to this definition">¶</a></dt>
<dd><p>Python code that is treated like it were put in a <tt class="docutils literal"><span class="pre">testsetup</span></tt> directive for
<em>every</em> file that is tested, and for every group. You can use this to
e.g. import modules you will always need in your doctests.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
<dl class="confval">
<dt id="confval-doctest_test_doctest_blocks">
<tt class="descname">doctest_test_doctest_blocks</tt><a class="headerlink" href="#confval-doctest_test_doctest_blocks" title="Permalink to this definition">¶</a></dt>
<dd><p>If this is a nonempty string (the default is <tt class="docutils literal"><span class="pre">'default'</span></tt>), standard reST
doctest blocks will be tested too. They will be assigned to the group name
given.</p>
<p>reST doctest blocks are simply doctests put into a paragraph of their own,
like so:</p>
<div class="highlight-rest"><pre>Some documentation text.
>>> print 1
1
Some more documentation text.</pre>
</div>
<p>(Note that no special <tt class="docutils literal"><span class="pre">::</span></tt> is used to introduce a doctest block; docutils
recognizes them from the leading <tt class="docutils literal"><span class="pre">>>></span></tt>. Also, no additional indentation is
used, though it doesn’t hurt.)</p>
<p>If this value is left at its default value, the above snippet is interpreted
by the doctest builder exactly like the following:</p>
<div class="highlight-rest"><pre>Some documentation text.
.. doctest::
>>> print 1
1
Some more documentation text.</pre>
</div>
<p>This feature makes it easy for you to test doctests in docstrings included
with the <a class="reference internal" href="autodoc.html#module-sphinx.ext.autodoc" title="sphinx.ext.autodoc: Include documentation from docstrings."><tt class="xref py py-mod docutils literal"><span class="pre">autodoc</span></tt></a> extension without marking them up with a
special directive.</p>
<p>Note though that you can’t have blank lines in reST doctest blocks. They
will be interpreted as one block ending and another one starting. Also,
removal of <tt class="docutils literal"><span class="pre"><BLANKLINE></span></tt> and <tt class="docutils literal"><span class="pre">#</span> <span class="pre">doctest:</span></tt> options only works in
<a class="reference internal" href="#directive-doctest" title="doctest directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">doctest</span></tt></a> blocks, though you may set <a class="reference internal" href="../config.html#confval-trim_doctest_flags"><tt class="xref std std-confval docutils literal"><span class="pre">trim_doctest_flags</span></tt></a> to
achieve the latter in all code blocks with Python console content.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="intersphinx.html" title="sphinx.ext.intersphinx – Link to other projects’ documentation"
>next</a> |</li>
<li class="right" >
<a href="autosummary.html" title="sphinx.ext.autosummary – Generate autodoc summaries"
>previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="../extensions.html" >Sphinx Extensions</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2011, Georg Brandl.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
2b39e69e45f9a0b2b3aece7339c56216
>
files
>
84
