[SciPy-dev] Fwd: [sage-devel] numpy in SAGE, etc.

[Gary Ruben]

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.