.. -*- 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: https://docs.pytest.org

.. toctree::
  :maxdepth: 2

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


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

This survey of 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


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
