http://bitofcheese.blogspot.com/2012/02/restructuredtext-to.html

pepe was a python pre-processor that was missing conditionals and some more.

PyExpander could be an alternative to provide more full-feature pre-processing support.

The project Madagascar has a nice article about Reproducible computational experiments using SCons. This could extend the concpets described in my blog entry regrading writing/programming experiments.

going from v0.9.0302 (Feb-2011) to v0.9.1104 (Nov-2011):

• setup new virtual env and create inital site
• update local_settings.py
• copy other media data
• migrate DB: see also 1 2
  • ./manage.py syncdb
  • ./manage.py migrate reversion 0001 --fake
  • ./manage.py migrate reversion
  • ./manage.py migrate pylucid 0001 --fake
  • ./manage.py migrate pylucid

Primarily Pandoc evaluates the possibility to write everything in a Pandoc input format and translate it from there into LaTeX and others. This input format could easily be reST.

Today something that has nothing todo directly with python development but that seems to be able to improve development workflow when using different computers.

So far I had one central svn repostory hosted on a publicly available server. Any commit from any of my three development machines went to that sever and the others synchronzied via this repository. Drawback: I always needed to be online to commit anything.

In addition I had Trac running to add information and a ticket system to my development but for this to use I needed to be online as well.

Cons regarding the current soluton:

• need to be always online / central repository approach
• somewhat complex setup (trac, svn, apache)

Pros so far:

• standard, proven tools
• very powerful and extensible (Trac)

To the rescue came Fossil :

Pros:

• all-in-one DVCS, wiki and ticket system
• one executable
• synchronizes everything: source, wiki and tickets

Cons:

• limited support for fossil as vcs (eg no vim add-in, no gui)
• Tcl like templating/scripting (a personal thing, I'm not into Tcl)

Overall it seems that the easy installation and the all-in-one approach outweighs the drawbacks and I give it a try.

searching for any kind of standard conventions to document functions and parameters in docstrings with reST I found the following

• scipy/numpy conventions

bruce is a pretty nice start regarding a python/reStructuredText based presentation tools but seems not to be maintained any more and has some drawbacks regarding scaling and 16:9 vs 4:3 format handling.

Looking for alternatives where I can "program" my presentation I stumbled upon pygamelab which is a mere collection of packages combined for developing games, but one or the other (if not the whole package) could be used for a python based presentation tool

Unfortunately the option --use-floating-images does not work wioth rst2pdf if reportlab 2.5 is installed. Currently (Mar-2011) the only solution seems to be to revert reportlab to 2.4.

See also an issue at the rst2pdf homepage.

currently I'm looking at how to document scripts that I've written do perform some experiments written in python as well as the results coming out of the execution of those scripts. The conundrum here is how to do this consistently (keep code, results & docs in sync) and how to relate these things, if at all. Literate Programming to the rescue, but maybe not in the original sense. Somewhere on one of the pages referenced below I've read a statement similar to this (link will follow if I find it again):

Donald E. Knuth was an author who wanted to write books as a main goal and wanted to document the code samples that he used, whereas programmers want to write code and want have the proper documentation in addition. Therefore the notion of pure literate programming, where you generate code and docs from one source, is not adequate as there's always one additional step in the development cycle, the tangling, to generate executable/compilable code out of the master source.

I fully concur: web is something for authors but how do we deal with a more code centric approach? I've setup the following constraints to come up with a solution:

1. the master source must be executable python
2. documentation part should be support reST
3. script output needs to be captured to be inserted into the result documentation (based on reST, see previous point)

So far the following I've identified the following options

• "real" literate programming, using s.th. like noweb (violates 2. and 3.)
• cog: a COde Generator (addresses mainly 3.)
• pylit: (addresses 1. & 2.)
• pyreport: combines all in an interesting way
• pweave: (violates 1.)

One good description integrating cog and Sphinx with paver can be found at Dough Hellmanns blog.

So far the a combination of pylit and cog is my favorite because, compared to pyreport, the documentation of the script (generated with pylit) and the documentation and explanation of the results (by executing cog) can be done separately. pyreport binds those two things quiet tightly together.

pyreport and also pweave have the very nice feature of automatically capturing all kinds of matplotlib based outputs, this is not inherently included in the pylit/cog combo.

A final decision is yet to be made.

(to be cont.)