rstdocs/examples/index.txt

   1 .. -*- rst-mode -*-
   2 ..
   3   restindex
   4       crumb: Examples
   5       page-title: Pylit - Examples
   6   /restindex
   7
   8 Examples
   9 ========
  10
  11 The following examples illustrate use cases for "literate programming with
  12 PyLit".
  13
  14 .. contents::
  15
  16 User scripts
  17 ------------
  18
  19 Generally, the literate source will not substitute a user guide, but can
  20 serve as base documentation as well as a reference.
  21
  22 The text parts can be used to structure the script, for additional
  23 explanations, documentation of variants and discussion why a specific
  24 approach was chosen.
  25
  26 `pylit.py`__
  27   is a script intended for the "end user". Both, command line
  28   and programmatic use is possible.
  29
  30   Sources: `pylit.py`__, `pylit.py.txt`__
  31
  32 __ pylit.py.html
  33 __ pylit.py
  34 __ pylit.py.txt
  35
  36
  37 `99bottles.py`__
  38   This is used as an introductory example to literate programming
  39   in the `LiteratePrograms.org Wiki`_. Riccardo Murri wrote a Python
  40   implementation.
  41
  42   Sources: `99bottles.py`__, `99bottles.py.txt`__
  43
  44 __ 99bottles.py.html
  45 __ 99bottles.py
  46 __ 99bottles.py.txt
  47 .. _LiteratePrograms.org Wiki:
  48      http://en.literateprograms.org/LiteratePrograms:Welcome
  49
  50 Python modules
  51 --------------
  52
  53 Typically, most of a Python modules's documentation is in docstrings as it
  54 should be available by pydoc_ (the Python help and module browser utility).
  55 Currently, docstrings are treated as code parts by PyLit.
  56
  57 However, literate comments can be used to add structure and documentation
  58 that is not intended for the end user of a module but for people trying to
  59 maintain or extend it (including the original author). Switching to the
  60 "text source" representation of the module greatly facilitates the writing
  61 of such "literate comments".
  62
  63 .. _pydoc: http://docs.python.org/lib/module-pydoc.html
  64
  65 `simplestates.py`__
  66   is a module providing the state machine used in earlier PyLit versions.
  67
  68   Sources: `simplestates.py`__, `simplestates.py.txt`__
  69
  70 __ simplestates.py.html
  71 __ simplestates.py
  72 __ simplestates.py.txt
  73
  74 Articles
  75 --------
  76
  77 `iterqueue.py`__
  78   is a survey over the various options and attempts to extend
  79   an iterator with methods for `peek`, `pushback` or `test of emptiness`.
  80
  81   It is also a Python module defining several examples of such rich
  82   iterators.
  83
  84   Sources: `iterqueue.py`__, `iterqueue.py.txt`__.
  85
  86 __ iterqueue.py.html
  87 __ iterqueue.py
  88 __ iterqueue.py.txt
  89
  90 Doctests
  91 --------
  92
  93 Python's `doctest`_ module runs tests on usage examples.
  94 However, running ``doctest`` on the code source will only run doctests
  95 within docstrings. In contrast, ``pylit --doctest`` will detect all
  96 doctests, in docstrings as well as in text blocks.
  97
  98 This way, doctests that do not need to become part of the on-line
  99 documentation can reside in the documentation blocks: Comprehensive
 100 tests can be placed in the same file as the tested code without resulting in
 101 bloated docstrings taking up precious ressources and loading time (as they
 102 will be stripped from the byte-compiled module).
 103
 104 As the containing module is not loaded when the file is tested with
 105 ``pylit --doctest``, a doctest block must import it before any of its
 106 objects can be used. An elegant solution is to give a usage example in the
 107 module's docstring.
 108
 109 `literate doctests`_ provides more details and two examples:
 110
 111
 112 `testmod_literate.py`_
 113    Literate example module with self-test (if run as ``__main__``) using
 114    `pylit.run_doctest`.
 115
 116 `testfile_literate.py`_
 117
 118    Literate example module tested by calling
 119    ``pylit --doctest testfile_literate.py`` or
 120    ``pylit --doctest testfile_literate.py.txt``.
 121
 122    It imports itself in the usage example and has a non-testing (albeit
 123    silly) default action if called from the command line.
 124
 125
 126 .. _doctest: http://docs.python.org/lib/module-doctest.html
 127 .. _literate doctests:    literate-doctests/index.html
 128 .. _testmod_literate.py: literate-doctests/testmod_literate.py
 129 .. _testfile_literate.py: literate-doctests/testfile_literate.py
 130
 131 Test suites
 132 -----------
 133
 134 Test suites are a good example for the advantages of literate programming.
 135 Documenting the rationale and design as well as test considerations can help
 136 a lot when maintaining and extending the suite.
 137
 138 The following unit test modules are tested using the nose_ unit
 139 test discovery & execution framework. (They should be compatible to
 140 `py.test`_.)
 141
 142 .. _nose: http://somethingaboutorange.com/mrl/projects/nose/
 143 .. _py.test: http://codespeak.net/py/current/doc/test.html
 144
 145
 146 `simplestates_test.py`__
 147   is not only the unit test module for simplestates.py,
 148   it also defines and tests variants of the state machine class.
 149
 150   Sources: `simplestates_test.py`__, `simplestates_test.py.txt`__.
 151
 152 __ simplestates_test.py.html
 153 __ simplestates_test.py
 154 __ simplestates_test.py.txt
 155
 156 `pylit_test.py`__
 157   contains the unit tests for the ``pylit.py`` text <--> code converter
 158
 159   Sources: `pylit_test.py`__, and `pylit_test.py.txt`__.
 160
 161 __ pylit_test.py.html
 162 __ pylit_test.py
 163 __ pylit_test.py.txt
 164
 165
 166 `iterqueue_test.py`__
 167   tests the functionality of the iterator wrapper classes defined in
 168   `iterqueue.py`
 169
 170   Sources: `iterqueue_test.py`__, `iterqueue_test.py.txt`__.
 171
 172 __ iterqueue_test.py.html
 173 __ iterqueue_test.py
 174 __ iterqueue_test.py.txt
 175
 176
 177 `iterqueue_speed_test.py`__
 178   Profiling of the iterator wrapper classes defined in
 179   `iterqueue.py`
 180
 181   Sources: `iterqueue_speed_test.py`__, `iterqueue_speed_test.py.txt`__
 182
 183 __ iterqueue_speed_test.py.html
 184 __ iterqueue_speed_test.py
 185 __ iterqueue_speed_test.py.txt
 186
 187
 188 Tutorials
 189 ---------
 190
 191 A tutorial is clearly more of a text document than a program. But usually, a
 192 lot of example code gets included. Converting the text source to commented
 193 code, it is easier to copy or paste code examples to and from scripts or an
 194 interactive program session. Re-converting indents the code snippets
 195 correctly so they will be literal blocks in the pretty print.
 196
 197 In Python, code examples can be given as both, code blocks and doctest_ blocks.
 198 With a 'usage' example that imports the code source as module, doctest
 199 blocks can also test examples from literal code blocks.
 200
 201 `swiginac_tutorial`_
 202   is an adaption of the `GiNaC tutorial`_ for doing Computer algebra with
 203   GiNaC_ and the Python programming language using the swiginac_ wrapper
 204   package.
 205
 206   It is work in progress, not completed yet.
 207
 208   Sources are in the `documentation folder`__ of the swiginac SVN repository.
 209
 210 __ http://svn.berlios.de/svnroot/repos/swiginac/trunk/doc/
 211
 212 .. _swiginac_tutorial:
 213     http://svn.berlios.de/svnroot/repos/swiginac/trunk/doc/swiginac_tutorial.py.html
 214 .. _GiNaC tutorial: http://www.ginac.de/tutorial/
 215 .. _GiNaC: http://www.ginac.de
 216 .. _swiginac: http://swiginac.berlios.de
 217
 218 Style sheets
 219 ------------
 220
 221 Not only code, but also cascading style sheets can gain from beeing made
 222 literate documents.
 223
 224 `pygments-default.css`__
 225   is a style sheet that provides colour to code blocks.
 226
 227   Sources: `pygments-default.css`__, `pygments-default.css.txt`__
 228
 229 __ ../features/pygments-default.css.html
 230 __ ../features/pygments-default.css
 231 __ ../features/pygments-default.css.txt
 232
 233 Configuration files
 234 -------------------
 235
 236 An interesting use case will be configuration files. Generating a template
 237 as well as user documentation from the same source helps to keep them
 238 synchronized.
 239
 240
 241