[SciPy-dev] Fwd: [sage-devel] numpy in SAGE, etc.
gruben at bigpond.net.au
Fri Dec 8 18:30:16 CST 2006
> 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
> 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)
Some (all?) of these specify their own markup. Here's a summary:
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
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
I also don't mind William's YADMUS.
>> 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:
or Ex2 etc. between each doctest.
More information about the Scipy-dev