Features

PyLit (Python-Literate) provides a plain but efficient tool for literate programming: a bidirectional converter between

• a “text” source with embedded code blocks and
• a “code” source with the documentation in comment blocks.

It is written in Python but should work with any programming language that provides a syntax for comment blocks.

The following features set PyLit apart from other literate programming frameworks

Dual Source

The program source can be either in “text” or “code” format:

• The “code” source can be debugged, compiled or executed with standard tools.
• The “text” source can be converted to HTML or LaTeX documents, e.g. with the Python Docutils or Sphinx.

The pylit module script converts the source between “text” and “code” formats.

Both formats hold the full information. Round-trips are possible without loss. [1]

[1]	Given the --strip option, PyLit will “export” to a format by stripping code or text parts during the conversion.

Advantages

• Work on code or documentation parts can be done in adapted editor modes or environments providing formatting tools, syntax highlight, outlining, and other conveniences.
• Debugging is straightforward (using the “code” format). Fixes are easily passed to the “text” format (just calling pylit.py on the “code” source).

Limitations

• The parallel existence of code and text formats might lead to confusion on which is the up to date, authoritative source.

  The pylit module has some provisions for dual source handling.

• While by default, an output file is not overwritten if it is newer than the input file, loss of changes can occur when both formats are edited in parallel.

• PyLit does not allow the specification of a separate output file for individual code blocks like e.g. noweb. The “dual source” concept limits the choice to one output file per input file. However, this can be compensated by the use of the include directive. See the tutorial for an example.

• Only one comment string (including whitespace) can be specified as “text block marker”.

  It would be possible to specify a list of matching comment strings (or a regular expression), however as the comment string is not stored in the text source, all text blocks will get one common comment string if (re)converted to code source – possibly loosing vital information.

Simplicity

Pylit is a pure Python module, i.e. a module written in Python and contained in a single file (pylit.py).

PyLit converts between a “text document with embedded code” and “commented code” but does not provide code re-ordering or multiple expansion of definitions. Some call this semi-literate programming.

Doing without “named chunks” reduces the complexity of the program and enables a line-by-line correspondence between text source and code source.

Markup with reStructuredText

PyLit uses reStructuredText from the Python Docutils for documentation text markup. [2]

• reStructuredText is an “ASCII-markup” language. Its syntax is very similar to common conventions used to structure “ASCII text” like e.g. emails. Thus it is more easy to read and to edit in a text editor than e.g. TeX, HTML, or XML.

• reStructuredText is well documented, and actively maintained.

• Special editor modes for editing reStructuredText already exist (see Editor Support for reStructuredText.)

• With Docutils, the text source can be converted to a nice looking, hyper-linked, browsable HTML documentation as well as to a LaTeX document (and with pdflatex further to a printer-ready PDF manual).

  The Python Documentation Generator Sphinx, adds support for more complex projects including extensive cross-references, automatic indices and automatic highlighting of source code.

Most of the time, a programmer will see the source in a “text editor”. With reStructuredText as documenting language, not only the pretty printed documentation, but also the source (be it in “text” or “code” format) is a “combination of documentation and source together in a fashion suited for reading by human beings”, i.e. a literate program according to the “inclusive” definition in the Literate Programming FAQ.

The tutorial and the examples show what code and text source may look like.

Syntax Highlight

While not available in standard Docutils, syntax highlight is an add-on in many reStructuredText based applications like the Sphinx Python Documentation Generator.

There is documentation and experimental code in the Docutils Sandbox project code-block directive to implement syntax highlight in core Docutils.

[2]	Actually, only the syntax for literal blocks is needed for PyLit to convert from text to code. If no pretty-printed or web-ready document is desired, the programmer does not need to know anything else about reStructuredText.

Python Doctest Support

Pylit supports Python doctests in documentation blocks. For details see the tutorial section and the literate doctests example.