rstdocs/examples/literate_doctests.txt

   1 .. -*- rst-mode -*-
   2 ..
   3   restindex
   4       crumb: Tutorial
   5       page-title: PyLit - Tutorial
   6       file: testmod_literate.py
   7       file: testfile_literate.py
   8   /restindex
   9
  10 How to write literate doctests with PyLit
  11 =========================================
  12
  13 .. sectnum::
  14 .. contents::
  15
  16 Doctest and PyLit
  17 -----------------
  18
  19 *Doctests* are a literate way of testing a Python script.  They are
  20 supported by the `doctest block`_ syntax in reStructured Text.
  21
  22 The `doctest module`_ searches strings for pieces of text that look like
  23 interactive Python sessions, and then executes those sessions to verify that
  24 they work exactly as shown.
  25
  26 * The most common way to use the doctest module is to check examples in all
  27   *docstrings* of a module with ``doctest.testmod()``, e.g. ::
  28
  29     if __name__ == "__main__":
  30         import doctest
  31         doctest.testmod()
  32
  33 * You can also check a *text* file as if it were a docstring by calling
  34   doctest from the command line, e.g. ::
  35
  36     python -c "import doctest; doctest.testfile('example.py.txt')"
  37
  38 However, both methods will not check doctest blocks in comments.
  39 This is why they will fail to find doctests in the text blocks of a source
  40 in code format (say ``example.py``). (See the tutorial_ for discussion.)
  41
  42 You can of course convert your source to text form and run doctest on it,
  43 but there is an option to facilitate literal doctests:
  44
  45 ``pylit --doctest``
  46   will check a literate source file for all doctests regardless of their
  47   location in docstrings or text parts. It can work with both, text or code
  48   format.
  49
  50   In order to do this, it will read the file, transform a code source to
  51   text format on-the-fly and feed the result to a DocTestParser_ object.
  52
  53 This way, it is possible to separate basic examples in doc strings from
  54 additional test in the literate source.
  55
  56
  57 Checking Examples in Docstrings and Documentation text
  58 ------------------------------------------------------
  59
  60 testmod_literate.py_
  61   is a "literate version" of the example in the `doctest module`_ doc that
  62   does a self test when called as `__main__`.
  63
  64   It calls `pylit.run_doctest` to find tests in both docstrings and
  65   documentation blocks.
  66
  67   Test this file with::
  68
  69      sh> python testmod_literate.py
  70      0 failures in 14 tests
  71
  72
  73 Checking Examples in a Literal Source File
  74 --------------------------------------------------------
  75
  76 testfile_literate.py_
  77   is a "literate version" of the example in the `doctest module`_ doc
  78   adapted for beeing tested with ``pylit --doctest``.
  79
  80   Test this file with::
  81
  82      sh> pylit --doctest testfile_literate.py
  83      0 failures in 19 tests
  84
  85
  86 .. References
  87    ==========
  88
  89 .. _doctest module:
  90 .. _Python doctests: http://docs.python.org/lib/module-doctest.html
  91 .. _DocTestParser: http://docs.python.org/lib/doctest-DocTestParser.html
  92 .. _Advanced API: http://docs.python.org/lib/doctest-advanced-api.html
  93
  94 .. _tutorial: /tutorial/
  95 .. _testmod_literate.py: testmod_literate.py
  96 .. _testfile_literate.py: testfile_literate.py
  97
  98
  99 .. _parsed-literal block:
 100     http://docutils.sf.net/docs/ref/rst/directives.html#parsed-literal-block
 101 .. _doctest block:
 102     http://docutils.sf.net/docs/ref/rst/restructuredtext.html#doctest-blocks
 103
 104