rstdocs/examples/index.txt

   1 .. -*- rst-mode -*-
   2
   3 Examples
   4 ========
   5
   6 The following examples illustrate use cases for "literate programming with
   7 PyLit".
   8
   9 Generally, the literate source will not substitute a user guide, but can
  10 serve as base documentation as well as reference.
  11
  12 The text parts can be used to structure the document, for additional
  13 explanations, documentation of variants and discussion why a specific
  14 approach was chosen.
  15
  16
  17 pylit.py
  18 --------
  19
  20 .. toctree::
  21   :maxdepth: 2
  22
  23   pylit.py
  24
  25
  26 Python Modules
  27 --------------
  28
  29 Typically, most of a Python module's documentation is in docstrings.
  30 Currently, docstrings are treated as code parts by PyLit.
  31
  32 However, literate comments can be used to add structure and documentation
  33 that is not intended for the end user of a module but for people trying to
  34 maintain or extend it (including the original author).
  35
  36 .. toctree::
  37   :maxdepth: 2
  38
  39   99bottles.py
  40   simplestates.py
  41
  42
  43 Doctests
  44 --------
  45
  46 Python's `doctest`_ module runs tests on usage examples.
  47 However, running ``doctest`` on the code source will only run doctests
  48 within docstrings. In contrast, ``pylit --doctest`` will detect all
  49 doctests, in docstrings as well as in text blocks.
  50
  51 This way, the docstrings can be kept concise while comprehensive tests can
  52 be placed in the code file without taking up precious resources and loading
  53 time (as they will be stripped from the byte-compiled module).
  54
  55 .. toctree::
  56    :maxdepth: 1
  57
  58    literate-doctests
  59    testfile_literate.py
  60    testmod_literate.py
  61
  62 .. _doctest: http://docs.python.org/library/doctest.html
  63
  64 Test Scripts
  65 ------------
  66
  67 Test suites are a good example for the advantages of literate programming.
  68 Documenting the rationale and design as well as test considerations can help
  69 a lot when maintaining and extending the tests.
  70
  71 The following unit test modules are tested using the nose_ unit
  72 test discovery & execution framework. (They should be compatible to
  73 `py.test`_.)
  74
  75 .. _nose: http://somethingaboutorange.com/mrl/projects/nose/
  76 .. _py.test: http://codespeak.net/py/dist/doc/test.html
  77
  78 .. toctree::
  79   :maxdepth: 2
  80
  81   pylit_test.py
  82   simplestates_test.py
  83   iterqueue_test.py
  84   iterqueue_speed_test.py
  85
  86
  87 Articles and Tutorials
  88 ----------------------
  89
  90 This survey over the various options and attempts to extend an iterator with
  91 methods for `peek`, `pushback` or `test of emptiness` is also a Python
  92 module defining several examples of such rich iterators.
  93
  94 .. toctree::
  95   :maxdepth: 1
  96
  97   iterqueue.py
  98
  99
 100 A tutorial is clearly more of a text document than a program. But usually, a
 101 lot of example code gets included. Converting the text source to commented
 102 code, it is easier to copy or paste code examples to and from scripts or an
 103 interactive program session. Re-converting indents the code snippets
 104 correctly so they will be literal blocks in the pretty print.
 105
 106 In Python, code examples can be given as both, code blocks and doctest_
 107 blocks.  With a 'usage' example that imports the code source as module,
 108 doctest blocks can also test examples from literal code blocks.
 109
 110 * `swiginac_tutorial`_
 111
 112   + An adaption of the `GiNaC tutorial`_ for doing Computer algebra with
 113     GiNaC_ and the Python programming language using the swiginac_ wrapper
 114     package. (incomplete.)
 115
 116   + The most current version and sources are in the `documentation folder`_
 117     of the swiginac SVN repository.
 118
 119 .. _swiginac_tutorial:
 120    http://swiginac.berlios.de/ginac-tutorial.py.html
 121 .. _documentation folder:
 122    http://svn.berlios.de/svnroot/repos/swiginac/trunk/doc/
 123 .. _GiNaC tutorial: http://www.ginac.de/tutorial/
 124 .. _GiNaC: http://www.ginac.de
 125 .. _swiginac: http://swiginac.berlios.de
 126
 127
 128 LaTeX Packages
 129 --------------
 130
 131 The "orthogonal" syntax of reStructuredText and LaTeX makes the documentation
 132 of a LaTeX package in the source document far more readable than using LaTeX
 133 markup.
 134
 135 .. toctree::
 136   :maxdepth: 2
 137
 138   listings-python-options.sty
 139   listings-tex-options.sty
 140   palatino-helvetica-courier.sty
 141
 142 * isomath_ (PDF__): Math for scientists
 143
 144   + LaTeX package for typesetting math according to International
 145     Standard ISO 31 `Quantities and units`.
 146
 147 __ ftp://dante.ctan.org/tex-archive/macros/latex/contrib/isomath/isomath.sty.pdf
 148
 149 Sources:
 150
 151 * listings-python-options.sty_, listings-tex-options.sty_,
 152   palatino-helvetica-courier.sty_
 153 * isomath.sty_, isomath.sty.txt_.
 154
 155 .. _listings-python-options.sty:
 156    http://docutils.sf.net/sandbox/stylesheets/listings-python-options.sty
 157 .. _listings-tex-options.sty:
 158    http://docutils.sf.net/sandbox/stylesheets/listings-tex-options.sty
 159 .. _palatino-helvetica-courier.sty:
 160    http://docutils.sf.net/sandbox/stylesheets/palatino-helvetica-courier.sty
 161 .. _isomath:
 162    http://dante.ctan.org/CTAN/macros/latex/contrib/isomath/isomath.sty.html
 163 .. _isomath.sty:
 164    ftp://dante.ctan.org/tex-archive/macros/latex/contrib/isomath/isomath.sty
 165 .. _isomath.sty.txt:
 166    ftp://dante.ctan.org/tex-archive/macros/latex/contrib/isomath/isomath.sty.txt
 167
 168 CSS Style Sheets
 169 ----------------
 170
 171 Also cascading style sheets can gain from being made literate documents.
 172
 173 .. toctree::
 174   :maxdepth: 1
 175
 176   pygments-default.css
 177
 178
 179 Configuration Files
 180 -------------------
 181
 182 Generating a template as well as user documentation from the same
 183 source helps to keep them synchronised:
 184
 185 .. toctree::
 186   :maxdepth: 1
 187
 188   ../conf.py