Literate Programming

From	Hans Georg Schaathun <hg@schaathun.net>
Newsgroups	comp.lang.python
Subject	Literate Programming
Date	2011-04-07 19:09 +0100
Organization	University of Bergen
Message-ID	<r7b178-602.ln1@svn.schaathun.net> (permalink)

Show all headers | View raw

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.

TIA
-- 
:-- Hans Georg

Back to comp.lang.python | Previous | Next — Next in thread | Find similar

Thread

Literate Programming Hans Georg Schaathun <hg@schaathun.net> - 2011-04-07 19:09 +0100
  Re: Literate Programming jkn <jkn_gg@nicorp.f9.co.uk> - 2011-04-07 12:31 -0700
  Re: Literate Programming Robert Kern <robert.kern@gmail.com> - 2011-04-07 16:21 -0500
    Re: Literate Programming Hans Georg Schaathun <hg@schaathun.net> - 2011-04-08 10:01 +0100
  Re: Literate Programming Jim <jim.hefferon@gmail.com> - 2011-04-08 05:22 -0700
    Re: Literate Programming Hans Georg Schaathun <hg@schaathun.net> - 2011-04-08 20:21 +0100
      Re: Literate Programming Jim <jim.hefferon@gmail.com> - 2011-04-09 03:45 -0700
        Re: Literate Programming Hans Georg Schaathun <hg@schaathun.net> - 2011-04-09 16:20 +0100
  Re: Literate Programming "Tim Arnold" <tim.arnold@sas.com> - 2011-04-08 12:58 -0400
    Re: Literate Programming Hans Georg Schaathun <hg@schaathun.net> - 2011-04-09 16:25 +0100
      Re: Literate Programming "Tim Arnold" <tim.arnold@sas.com> - 2011-04-11 12:39 -0400

csiph-web