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