A little follow-up from my post on literate programming. A less radical option is to produce documentation using a generator such as Doxygen. I used this tool a long while ago to document C++ code but since then have been using Java and the javadoc tool is doing a fairly decent job. However, recently I started coding in Python and I am also dabbling in Fortran, so I was looking for a tool that works for the different languages I am using today and Doxygen just fits the bill.
I was impressed by how easy it was to generate quality documentation for my existing Python code - just run
doxygen -g and a new Doxygen config file will be written to disk. With a few tweaks such as turning on recursive inclusion of Python modules and telling Doxygen that I have Graphviz and want class inheritance diagrams I was up and running. I really like the fact that this works well across different languages, so I can now help some scientist friends to better document their Fortran code.