.. -*- rst-mode -*-

Examples
========

The following examples illustrate use cases for "literate programming with
PyLit".

Generally, the literate source will not substitute a user guide, but can
serve as base documentation as well as reference.

The text parts can be used to structure the document, for additional
explanations, documentation of variants and discussion why a specific
approach was chosen.


pylit.py
--------

.. toctree::
  :maxdepth: 2

  pylit.py


Python Modules
--------------

Typically, most of a Python module's documentation is in docstrings.
Currently, docstrings are treated as code parts by PyLit.

However, literate comments can be used to add structure and documentation
that is not intended for the end user of a module but for people trying to
maintain or extend it (including the original author).

.. toctree::
  :maxdepth: 2

  99bottles.py
  simplestates.py


Doctests
--------

Python's `doctest`_ module runs tests on usage examples.
However, running ``doctest`` on the code source will only run doctests
within docstrings. In contrast, ``pylit --doctest`` will detect all
doctests, in docstrings as well as in text blocks.

This way, the docstrings can be kept concise while comprehensive tests can
be placed in the code file without taking up precious resources and loading
time (as they will be stripped from the byte-compiled module).

.. toctree::
   :maxdepth: 1

   literate-doctests
   testfile_literate.py
   testmod_literate.py

.. _doctest: http://docs.python.org/library/doctest.html

Test Scripts
------------

Test suites are a good example for the advantages of literate programming.
Documenting the rationale and design as well as test considerations can help
a lot when maintaining and extending the tests.

The following unit test modules are tested using the nose_ unit
test discovery & execution framework. (They should be compatible to
`py.test`_.)

.. _nose: http://somethingaboutorange.com/mrl/projects/nose/
.. _py.test: http://codespeak.net/py/dist/doc/test.html

.. toctree::
  :maxdepth: 2

  pylit_test.py
  simplestates_test.py
  iterqueue_test.py
  iterqueue_speed_test.py


Articles and Tutorials
----------------------

This survey over the various options and attempts to extend an iterator with
methods for `peek`, `pushback` or `test of emptiness` is also a Python
module defining several examples of such rich iterators.

.. toctree::
  :maxdepth: 1

  iterqueue.py


A tutorial is clearly more of a text document than a program. But usually, a
lot of example code gets included. Converting the text source to commented
code, it is easier to copy or paste code examples to and from scripts or an
interactive program session. Re-converting indents the code snippets
correctly so they will be literal blocks in the pretty print.

In Python, code examples can be given as both, code blocks and doctest_
blocks.  With a 'usage' example that imports the code source as module,
doctest blocks can also test examples from literal code blocks.

* `swiginac_tutorial`_

  + An adaption of the `GiNaC tutorial`_ for doing Computer algebra with
    GiNaC_ and the Python programming language using the swiginac_ wrapper
    package. (incomplete.)

  + The most current version and sources are in the `documentation folder`_
    of the swiginac SVN repository.

.. _swiginac_tutorial:
   http://swiginac.berlios.de/ginac-tutorial.py.html
.. _documentation folder:
   http://svn.berlios.de/svnroot/repos/swiginac/trunk/doc/
.. _GiNaC tutorial: http://www.ginac.de/tutorial/
.. _GiNaC: http://www.ginac.de
.. _swiginac: http://swiginac.berlios.de


LaTeX Packages
--------------

The "orthogonal" syntax of reStructuredText and LaTeX makes the documentation
of a LaTeX package in the source document far more readable than using LaTeX
markup.

.. toctree::
  :maxdepth: 2

  listings-python-options.sty
  listings-tex-options.sty
  palatino-helvetica-courier.sty

* isomath_ (PDF__): Math for scientists

  + LaTeX package for typesetting math according to International
    Standard ISO 31 `Quantities and units`.

__ ftp://dante.ctan.org/tex-archive/macros/latex/contrib/isomath/isomath.sty.pdf

Sources:

* listings-python-options.sty_, listings-tex-options.sty_,
  palatino-helvetica-courier.sty_
* isomath.sty_, isomath.sty.txt_.

.. _listings-python-options.sty:
   http://docutils.sf.net/sandbox/stylesheets/listings-python-options.sty
.. _listings-tex-options.sty:
   http://docutils.sf.net/sandbox/stylesheets/listings-tex-options.sty
.. _palatino-helvetica-courier.sty:
   http://docutils.sf.net/sandbox/stylesheets/palatino-helvetica-courier.sty
.. _isomath:
   http://dante.ctan.org/CTAN/macros/latex/contrib/isomath/isomath.sty.html
.. _isomath.sty:
   ftp://dante.ctan.org/tex-archive/macros/latex/contrib/isomath/isomath.sty
.. _isomath.sty.txt:
   ftp://dante.ctan.org/tex-archive/macros/latex/contrib/isomath/isomath.sty.txt

CSS Style Sheets
----------------

Also cascading style sheets can gain from being made literate documents.

.. toctree::
  :maxdepth: 1

  pygments-default.css


Configuration Files
-------------------

Generating a template as well as user documentation from the same
source helps to keep them synchronised:

.. toctree::
  :maxdepth: 1

  ../conf.py
