Hi Jonathan,
I'm all for a standard format (and certainly all for encouraging documentation (although I'm a bit skeptical that agreeing on a format is suddenly going to open the floodgates of heretofore amorphous documentation that the SciPy community has been hoarding to themselves)).
It's a shame that he felt the need to invent YADMUS (Yet Another Docstring MarkUp Specification), though. Python has too many systems for this already.
Can you suggest something existing for the extra markup? I've never used anything fancier than plain docstrings. The other existing options seem to be (from a brief look) reST/docutils epydoc pythondoc doxygen happydoc Some (all?) of these specify their own markup. Here's a summary: <http://epydoc.sourceforge.net/relatedprojects.html> I'm told by a doxygen advocate that it now has proper Python support and should be considered. If someone else has looked at these maybe they can pipe in, otherwise I may have to find out the relative advantages and disadvantages. I like the idea of supporting LaTeX markup, cross references. I like the idea of supporting matplotlib examples (opinions?). I like Mark's idea of a wiki page per function/class/module if it can be done. I also don't mind William's YADMUS.
I'd also specify some way of delineating examples so that they can be preprocessed and run as part of the unit tests.
You mean like doctest?
The problem I see with plain doctests is that you can't easily choose to run, say, just the 3rd example out of 5 without specifying some sort of delineation between them, but this would be easy; something like: # Ex1: or Ex2 etc. between each doctest. Gary R.