I need to make my work as reproducible as is reasonably possible. A reader should see my code, English-language descriptions of what I did and why I did it, embedded graphs, and tables of results. The software side of my work involves a series of R commands, short Python scripts (typically one-off, shorter than 100 lines), and shell commands to run software packages I've created. The code for these larger programs lives in source control. The standard tool for solving this problem in an R-only world is Sweave (described http://www.stat.umn.edu/~charlie/Sweave/). Sweave documents are literate programming, which is great. However, Sweave doesn't (to my knowledge) solve my problem because I don't live exclusively in R.
My current method is to create a Word document that is formatted with monotype fonts for code blocks and nicer fonts for descriptions, headlines, etc. This puts the entire analysis in one place and looks good. I can drop in Endnote references, paste in screen captures, and paste in Excel tables. This method is a very fast way to work. Importantly, I can email this document to non-technical collaborators and they can read it easily. However, the document cannot be "run in place". To redo my results would involve a lot of cutting and pasting. I also need a Mac or Windows box to work this way.
Has anyone got a better solution than this? "Generate HTML documents with blogging software" would possibly be acceptable if it were easy enough to do and powerful enough.
+1 for Sphinx. It's based on restructuredText (reST). Extremely powerful: our lab uses it for code documentation and for lab notebooks. Works beautifully and has a very nice indexing feature. Check out the matplotlib website for a swell example.
.. code-block:: r
Will do some of what you want if you're mixing code. And you could perhaps do file includes in conjunction with this.