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

• pylit.py
  • Literate programming with reStructuredText

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).

• 99bottles.py
  • Introductory Example to Literate Programming
• simplestates.py
  • Generic state machine class using iterators

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).

• How to write literate doctests with PyLit
• testfile_literate
• testmod_literate

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.)

• pylit_test.py
  • Test pylit.py Python Module
• simplestates_test.py:
  • Test the simplestates.py generic state machine
• iterqueue_test.py
  • Test the iterator wrappers from iterqueue.py
• iterqueue_speed_test.py
  • Profiling the iterqueue extended iterator classes

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.

• Extending Iterators for use as Queue

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.

• Settings for the listings package with Python
  • Font settings
  • Default language
  • Style
  • Column alignment
• listings-tex-options.sty
  • highlight LaTeX code with lstlistings
• palatino-helvetica-courier.sty
  • Recommended Font Settings for Palatino, Helvetica, and Courier

• isomath (PDF): Math for scientists

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

Sources:

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

• isomath.sty, isomath.sty.txt.

CSS Style Sheets

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

• Stylesheet for reStructured Text code blocks

Configuration Files

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

• conf.py – Sphinx configuration for PyLit