* Add docs for sphinx.ext.doctest.

* Update parse_node functions.

doc/Makefile

@@ -64,3 +64,7 @@ linkcheck:
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in .build/linkcheck/output.txt."
+
+doctest:
+	mkdir -p .build/doctest .build/doctrees
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) .build/doctest

doc/conf.py

@@ -21,7 +21,7 @@ sys.path.append(os.path.dirname(__file__))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.addons.*') or your custom ones.
-extensions = ['ext', 'sphinx.ext.autodoc']
+extensions = ['ext', 'sphinx.ext.autodoc', 'sphinx.ext.doctest']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['.templates']

doc/ext.py

@@ -13,23 +13,25 @@ from sphinx import addnodes
 
 dir_sig_re = re.compile(r'\.\. ([^:]+)::(.*)$')
 
-def parse_directive(sig, signode):
+def parse_directive(env, sig, signode):
     if not sig.startswith('.'):
         sig = '.. %s::' % sig
         signode += addnodes.desc_name(sig, sig)
-        return
+        return sig
     m = dir_sig_re.match(sig)
     if not m:
         signode += addnodes.desc_name(sig, sig)
-        return
+        return sig
     name, args = m.groups()
-    name = '.. %s::' % name
-    signode += addnodes.desc_name(name, name)
+    dec_name = '.. %s::' % name
+    signode += addnodes.desc_name(dec_name, dec_name)
     signode += addnodes.desc_classname(args, args)
+    return name
 
 
-def parse_role(sig, signode):
+def parse_role(env, sig, signode):
     signode += addnodes.desc_name(':%s:' % sig, ':%s:' % sig)
+    return sig
 
 
 def setup(app):

doc/ext/appapi.rst

@@ -8,12 +8,12 @@ This function is called at initialization time with one argument, the
 application object representing the Sphinx process.  This application object has
 the following public API:
 
-.. method:: Application.add_builder(builder)
+.. method:: Sphinx.add_builder(builder)
 
    Register a new builder.  *builder* must be a class that inherits from
    :class:`~sphinx.builder.Builder`.
 
-.. method:: Application.add_config_value(name, default, rebuild_env)
+.. method:: Sphinx.add_config_value(name, default, rebuild_env)
 
    Register a configuration value.  This is necessary for Sphinx to recognize
    new values and set default values accordingly.  The *name* should be prefixed
@@ -22,16 +22,16 @@ the following public API:
    in the setting only takes effect when a document is parsed -- this means that
    the whole environment must be rebuilt.
 
-.. method:: Application.add_event(name)
+.. method:: Sphinx.add_event(name)
 
    Register an event called *name*.
 
-.. method:: Application.add_node(node)
+.. method:: Sphinx.add_node(node)
 
    Register a Docutils node class.  This is necessary for Docutils internals.
    It may also be used in the future to validate nodes in the parsed documents.
 
-.. method:: Application.add_directive(name, cls, content, arguments, **options)
+.. method:: Sphinx.add_directive(name, cls, content, arguments, **options)
 
    Register a Docutils directive.  *name* must be the prospective directive
    name, *func* the directive function for details about the signature and
@@ -42,13 +42,13 @@ the following public API:
 
    .. XXX once we target docutils 0.5, update this
    
-.. method:: Application.add_role(name, role)
+.. method:: Sphinx.add_role(name, role)
 
    Register a Docutils role.  *name* must be the role name that occurs in the
    source, *role* the role function (see the `Docutils documentation
    <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ on details).
 
-.. method:: Application.add_description_unit(directivename, rolename, indexdesc='', parse_node=None)
+.. method:: Sphinx.add_description_unit(directivename, rolename, indexdesc='', parse_node=None)
 
    This method is a very convenient way to add a new type of information that
    can be cross-referenced.  It will do this:
@@ -59,8 +59,9 @@ the following public API:
      description units.
    * If you provide *parse_node*, it must be a function that takes a string and
      a docutils node, and it must populate the node with children parsed from
-     the string.  See the :file:`ext.py` file in the source for this
-     documentation for details.
+     the string.  It must then return the name of the item to be used in
+     cross-referencing and index entries.  See the :file:`ext.py` file in the
+     source for this documentation for an example.
 
    For example, if you have this call in a custom Sphinx extension::
 
@@ -79,7 +80,7 @@ the following public API:
    For the role content, you have the same options as for standard Sphinx roles
    (see :ref:`xref-syntax`).
 
-.. method:: Application.connect(event, callback)
+.. method:: Sphinx.connect(event, callback)
 
    Register *callback* to be called when *event* is emitted.  For details on
    available core events and the arguments of callback functions, please see
@@ -88,11 +89,11 @@ the following public API:
    The method returns a "listener ID" that can be used as an argument to
    :meth:`disconnect`.
 
-.. method:: Application.disconnect(listener_id)
+.. method:: Sphinx.disconnect(listener_id)
 
    Unregister callback *listener_id*.
 
-.. method:: Application.emit(event, *arguments)
+.. method:: Sphinx.emit(event, *arguments)
 
    Emit *event* and pass *arguments* to the callback functions.  Do not emit
    core Sphinx events in extensions!

doc/ext/doctest.rst

@@ -1,5 +1,151 @@
+.. highlight:: rest
+
 :mod:`sphinx.ext.doctest` -- Test snippets in the documentation
 ===============================================================
 
 .. module:: sphinx.ext.doctest
    :synopsis: Test snippets in the documentation.
+
+.. index:: pair: automatic; testing
+           single: doctest
+           pair: testing; snippets
+
+
+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.
+
+Within one document, test code is partitioned in *groups*, where each group
+consists of:
+
+* zero or more *setup code* blocks (e.g. importing the module to test)
+* one or more *test* blocks
+
+When building the docs with the ``doctest`` 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.
+
+There are two kinds of test blocks:
+
+* *doctest-style* blocks mimic interactive sessions by interleaving Python code
+  (including the interpreter prompt) and output.
+
+* *code-output-style* blocks consist of an ordinary piece of Python code, and
+  optionally, a piece of output for that code.
+
+The doctest extension provides four directives.  The *group* argument is
+interpreted as follows: if it is empty, the block is assigned to the group named
+``default``.  If it is ``*``, the block is assigned to all groups (including the
+``default`` group).  Otherwise, it must be a comma-separated list of group
+names.
+
+.. directive:: .. testsetup:: [group]
+
+   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.
+
+.. directive:: .. doctest:: [group]
+
+   A doctest-style code block.  You can use standard :mod:`doctest` flags for
+   controlling how actual output is compared with what you give as output.  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`` (not comparing tracebacks),
+   ``DONT_ACCEPT_TRUE_FOR_1`` (by default, doctest accepts "True" in the output
+   where "1" is given -- this is a relic of pre-Python 2.2 times).
+
+.. directive:: .. testcode:: [group]
+
+   A code block for a code-output-style test.
+
+.. directive:: .. testoutput:: [group]
+
+   The corresponding output for the last :dir:`testcode` block.
+
+   This directive supports two options:
+
+   * ``hide``, a flag option, hides the output block in other builders.  By
+     default it is shown as a literal block without highlighting.
+
+   * ``options``, a string option, can be used to give doctest flags
+     (comma-separated) just like in normal doctest blocks.
+
+   Example::
+
+      .. testoutput::
+         :hide:
+         :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
+
+         Output text.
+
+
+The following is an example for the usage of the directives.  The test via
+:dir:`doctest` and the test via :dir:`testcode` and :dir:`testoutput` are
+completely equivalent. ::
+
+   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!
+
+
+There are also these config values for customizing the doctest extension:
+
+.. confval:: doctest_path
+
+   A list of directories that will be added to :data:`sys.path` when the doctest
+   builder is used.  (Make sure it contains absolute paths.)
+
+.. confval:: doctest_test_doctest_blocks
+
+   If ``True`` (the default), standard reST doctest blocks will be tested too.
+   They will be assigned to a group named ``doctest_block``.
+
+   reST doctest blocks are simply doctests put into a paragraph of their own,
+   like so::
+
+      Some documentation text.
+
+      >>> print 1
+      1
+
+      Some more documentation text.
+
+   If this value is true, the above snippet is interpreted by the doctest
+   builder exactly like the following::
+
+      Some documentation text.
+
+      .. doctest:: doctest_block
+
+         >>> print 1
+         1
+
+      Some more documentation text.      
+
+   This feature makes it easy for you to test doctests in docstrings included
+   with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a
+   special directive.