Language agnostic tools for software documentation

Maintaining documentation of large codes is a drag, which is why a variety of tools allow you to embed your documentation right within the code, making the process natural and probably improving your code at the same time. Coding in Java? JavaDocs is great. C++? Try Doxygen.

But what happens if you have core components in C++, wrappers in Python, and extensions in R?

My solution, developed for Quantitative Sustainability ORG is to extend upon Sphinx. One can use the default markup to annotate files, regardless of language, to distinguish modules, classes, and functions.

However, when building the documentation, even Sphinx expects monogamous commitment to a single language, not some debauched combination. So, to help Sphinx out, I wrote a BASH script file2doc.sh to strip documentation from files and install it in Sphinx's tree, saving it the problem of distinguishing Java from JPython, C from COBOL. The wrapper script source2doc.sh allows entirely source trees to be documented. As a bonus, source files are automatically linked to their documentation (and vice versa).

For a detailed example of this approach in action, browse the documentation at QuantitativeSustainability.org/source/.