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
  48
  49 Python modules
  50 --------------
  51
  52 Typically, most of a Python modules's documentation is in docstrings as it
  53 should be available by pydoc_ (the Python help and module browser utility).
  54 Currently, docstrings are treated as code parts by PyLit.
  55
  56 However, literate comments can be used to add structure and documentation
  57 that is not intended for the end user of a module but for people trying to
  58 maintain or extend it (including the original author). Switching to the
  59 "text source" representation of the module greatly facilitates the writing
  60 of such "literate comments".
  61
  62 .. _pydoc: http://docs.python.org/lib/module-pydoc.html
  63
  64 `simplestates.py`__
  65   is the module providing the state machine used in PyLit.
  66
  67   Sources: `simplestates.py`__, `simplestates.py.txt`__
  68
  69 __ simplestates.py.html
  70 __ simplestates.py
  71 __ simplestates.py.txt
  72
  73 Articles
  74 --------
  75
  76 `iterqueue.py`__
  77   is a survey over the various options and attempts to extend
  78   an iterator with methods for `peek`, `pushback` or `test of emptiness`.
  79
  80   It is also a Python module defining several examples of such rich
  81   iterators.
  82
  83   BTW: Running ``doctest`` on the code source will only run doctests within
  84   docstrings. In contrast, ``pylit --doctest`` will detect all doctests, in
  85   docstrings as well as in text blocks.
  86
  87   Sources: `iterqueue.py`__, `iterqueue.py.txt`__.
  88
  89 __ iterqueue.py.html
  90 __ iterqueue.py
  91 __ iterqueue.py.txt
  92
  93 Test suites
  94 -----------
  95
  96 Test suites are a good example for the advantages of literate programming.
  97 Documenting the rationale and design as well as test considerations can help
  98 a lot when maintaining and extending the suite.
  99
 100 The following unit test modules are tested using the nose_ unit
 101 test discovery & execution framework. (They should be compatible to
 102 `py.test`_.)
 103
 104 .. _nose: http://somethingaboutorange.com/mrl/projects/nose/
 105 .. _py.test: http://codespeak.net/py/current/doc/test.html
 106
 107
 108 `simplestates_test.py`__
 109   is not only the unit test module for simplestates.py,
 110   it also defines and tests variants of the state machine class.
 111
 112   Sources: `simplestates_test.py`__, `simplestates_test.py.txt`__.
 113
 114 __ simplestates_test.py.html
 115 __ simplestates_test.py
 116 __ simplestates_test.py.txt
 117
 118 `pylit_test.py`__
 119   contains the unit tests for the ``pylit.py`` text <--> code converter
 120
 121   Sources: `pylit_test.py`__, and `pylit_test.py.txt`__.
 122
 123 __ pylit_test.py.html
 124 __ pylit_test.py
 125 __ pylit_test.py.txt
 126
 127
 128 `iterqueue_test.py`__
 129   tests the functionality of the iterator wrapper classes defined in
 130   `iterqueue.py`
 131
 132   Sources: `iterqueue_test.py`__, `iterqueue_test.py.txt`__.
 133
 134 __ iterqueue_test.py.html
 135 __ iterqueue_test.py
 136 __ iterqueue_test.py.txt
 137
 138
 139 `iterqueue_speed_test.py`__
 140   Profiling of the iterator wrapper classes defined in
 141   `iterqueue.py`
 142
 143   Sources: `iterqueue_speed_test.py`__, `iterqueue_speed_test.py.txt`__
 144
 145 __ iterqueue_speed_test.py.html
 146 __ iterqueue_speed_test.py
 147 __ iterqueue_speed_test.py.txt
 148
 149
 150 Tutorials
 151 ---------
 152
 153 A tutorial is clearly more of a text document than a program. But usually, a
 154 lot of example code gets included. Converting the text source to commented
 155 code, it is easier to copy or paste code examples to and from scripts or an
 156 interactive program session. Re-converting indents the code snippets
 157 correctly so they will be literal blocks in the pretty print.
 158
 159 `ginac-tutorial.py`__
 160   is an adaption of the `GiNaC tutorial`_ for doing Computer algebra with
 161   GiNaC_ and the Python_ programming language using the swiginac_ wrapper
 162   package.
 163
 164   It is a work in progress, not completed yet.
 165
 166   Sources: `ginac-tutorial.py`__, `ginac-tutorial.py.txt`__
 167
 168 __ ginac-tutorial.py.html
 169 __ ginac-tutorial.pyr2w
 170 __ ginac-tutorial.py.txt
 171
 172 .. _`GiNaC tutorial`: http://www.ginac.de/tutorial/
 173 .. _GiNaC: http://www.ginac.de
 174 .. _Python: http://www.python.org
 175 .. _swiginac: http://swiginac.berlios.de
 176 .. _LiteratePrograms.org Wiki:
 177      http://en.literateprograms.org/LiteratePrograms:Welcome
 178
 179
 180
 181