rstdocs/examples/literate-doctests.txt

   1 .. -*- rst-mode -*-
   2
   3 How to write literate doctests with PyLit
   4 =========================================
   5
   6 Python Doctest Module
   7 ---------------------
   8
   9 *Doctests* are a literate way of testing a Python script.  They are
  10 supported by the `doctest block`_ syntax in reStructuredText.
  11
  12   The `doctest module`_ searches strings for pieces of text that look like
  13   interactive Python sessions, and then executes those sessions to verify
  14   that they work exactly as shown.
  15
  16   There are several common ways to use doctest:
  17
  18   * To check that a module's docstrings are up-to-date by verifying that all
  19     interactive examples still work as documented.
  20
  21   * To perform regression testing by verifying that interactive examples
  22     from a test file or a test object work as expected.
  23
  24   * To write tutorial documentation for a package, liberally illustrated
  25     with input-output examples. Depending on whether the examples or the
  26     expository text are emphasised, this has the flavor of "literate
  27     testing" or "executable documentation".
  28
  29   -- Python Library Reference for the `doctest module`_
  30
  31
  32 Doctest and PyLit
  33 -----------------
  34
  35 The most common way to use the doctest module is to check examples in all
  36 *docstrings* of a module with ``doctest.testmod()``, e.g. ::
  37
  38     if __name__ == "__main__":
  39         import doctest
  40         doctest.testmod()
  41
  42 You can also check a *text* file as if it were a docstring by calling
  43 doctest from the command line, e.g. ::
  44
  45     sh> python -c "import doctest; doctest.testfile('example.py.txt')"
  46
  47 However, both methods will not check doctest blocks in comments. This is
  48 why they will fail to find doctests in the text blocks of a literate source
  49 in code format. (See the tutorial_ for discussion.)
  50
  51 You can of course convert your source to text form and run
  52 `doctest.testfile` on it. To simplify the task, Pylit supports
  53 `Python doctests`_ in a literate source with an option::
  54
  55     sh> pylit --doctest example.py
  56
  57 will check a literate source file for all doctests regardless of their
  58 location in docstrings or text parts. It can work with both, text or code
  59 format.
  60
  61 In order to do this, it will read the file, transform a code source to text
  62 format on-the-fly and feed the result to a DocTestParser_ object.
  63 I.e., no text source file will be created if ``pylit --doctest`` is
  64 called on a code source file.
  65
  66 This way, it is possible to separate basic examples in doc strings from
  67 additional test in the literate source.
  68
  69
  70 Examples
  71 --------
  72
  73 `testmod_literate <testmod_literate.py.html>`_
  74   is a "literate version" of the example in the `doctest module`_ doc that
  75   does a self test when called as `__main__`.
  76
  77   It calls `pylit.run_doctest` to find tests in both docstrings and
  78   documentation blocks.
  79
  80   Test this file with::
  81
  82      #> python testmod_literate.py
  83      0 failures in 14 tests
  84
  85   Sources: `<testmod_literate.py>`_, `<testmod_literate.py.txt>`_
  86
  87 `testfile_literate <testfile_literate.py.html>`_
  88   is a "literate version" of the example in the `doctest module`_ doc
  89   adapted for being tested with ``pylit --doctest``.
  90
  91   Test this file with::
  92
  93      #> pylit --doctest testfile_literate.py
  94      0 failures in 19 tests
  95
  96    It imports itself in the usage example and has a non-testing (albeit
  97    silly) default action if called from the command line.
  98
  99    Sources: `<testfile_literate.py>`_, `<testfile_literate.py.txt>`_
 100
 101 .. References
 102    ==========
 103
 104 .. _doctest module:
 105 .. _Python doctests:
 106    http://docs.python.org/library/doctest.html
 107 .. _DocTestParser:
 108    http://docs.python.org/library/doctest.html#doctestparser-objects
 109 .. _Advanced API:
 110    http://docs.python.org/library/doctest-advanced-api.html
 111
 112 .. _tutorial: ../tutorial/index.html#doctests
 113
 114 .. _parsed-literal block:
 115    http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block
 116 .. _doctest block:
 117    http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#doctest-blocks
 118
 119