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.
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).
Python’s doctest module runs tests on usage examples.
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).
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.)
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.
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.
isomath (PDF): Math for scientists
LaTeX package for typesetting math according to International Standard ISO 31 Quantities and units.
CSS Style Sheets¶
Also cascading style sheets can gain from being made literate documents.
Generating a template as well as user documentation from the same source helps to keep them synchronised: