Literate Programming

[Hans Georg Schaathun]

On Thu, 07 Apr 2011 16:21:52 -0500, Robert Kern
  <robert.kern at gmail.com> wrote:
:  http://sphinx.pocoo.org/markup/code.html
: 
:  As far as I can tell, it just works. See here for an example:
: 
:  http://ipython.scipy.org/doc/nightly/html/interactive/reference.html

Maybe I did not express myself clearly.  I don't have a problem with
highlighting or indentation within a single, complete and continuous
block of code.
I get trouble when I insert explaining text within nested blocks, 
especially when I do it at different levels of indentation.
In the pages you cite, I cannot find a single example which tries to 
do this.

So something like this is fine:

<code>
# This is a long and complex block::

if mytest():
   for i in myList():
     foobar(i)
else:
   for i in yourList():
     boofar(i)
</code>

If I do the following, sphinx cannot keep up ...

<code>
# This block should be explained step by step::

if mytest():

# Bla, blah blah...
#
#   ::

   for i in myList():

# The :func:`foobar` function is an interesting choice here ... blah
#
#   ::

     foobar(i)

# Otherwise, myList might not be defined, so we need yours::

else:

# More blah...
#
#   ::

   for i in yourList():

# And here we go again::

     boofar(i)
</code>

Highlighting tends to break starting from `else', and indentation breaks
at the second or third level.

-- 
:-- Hans Georg