Literate Programming

Hans Georg Schaathun hg at
Thu Apr 7 14:09:31 EDT 2011

Has anyone found a good system for literate programming in python?

I have been trying to use pylit/sphinx/pdflatex to generate
technical documentation.  The application is scientific/numerical
programming, so discussing maths in maths syntax in between 
python syntax is important.

While I like the style, there are several things which do not
work as they should.

One problem is that reST strips the indentation of code.  When
documentation intersperses nested blocks, it would look better
if indentation was preserved so that the semantics of the code
is clear in the documentation.  Are there any tricks to achieve
this in sphinx, or other systems which get it right?

Another problem is the the syntax highlighting sometimes get 
confused.  Most of the time, keywords are highlighted, but 
sometimes they don't.  For instance, documentation between
if and else in a conditional, seems to prevent sphinx from
recognising else.  I also have some problems with 'def´ not
being recognised, where I have absolutely no clue as to why.
Are there any solutions to this?

Third problem, when I use automethod to get the docstring
prettyprinted, it would be neat if the verbatim docstring
definition did not appear as well.  Any hints?

I am not dead set on keeping pylit/sphinx, although it would
be good to minimise the amount of doc code requiring rewriting.
The most important thing is to get a working system where I 
could write a tutorial explaining both the python syntax and
the maths of a problem completely unambiguously.

:-- Hans Georg

More information about the Python-list mailing list