Coding with Fountain Pens

It seems we’re always on the lookout for a workable inline code documentation system.  The pros and cons of doing this are always fighting it out, with a significant con being that this tends towards overdocumentation.

At any rate, I just read that the Python documentation switched over from LaTeX to reStructuredText.   One of the common drawbacks of inline documentation is that some nasty tags are required to markup the text.  reStructuredText avoids this problem by using quite intuitive underlining, indentation and numeric lists, such that the documentation text is formatted essentially as one would format it for normal plaintext readability.

This is a sample python script documented with  reST. You can paste one of the docstrings into this online renderer to see the sample output.  Rendering would normally be done with Docutils.