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

Jonathan Guyer guyer at nist.gov
Fri Dec 8 20:15:23 CST 2006


On Dec 8, 2006, at 7:30 PM, Gary Ruben wrote:

> 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

Right. These all exist. They all have their issues and their  
benefits. I just don't see a need for yet another one.

We happen to use the epydoc tool to process reST markup.


> I like the idea of supporting LaTeX markup, cross references.

Alan addresses this.

> I like the idea of supporting matplotlib examples (opinions?).

Supporting how? You certainly can have matplotlib code in doctest  
lines and you can use reST's ..image:: declaration to include output  
in your documentation.

> 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.

It's not that I mind his markup; it's that I don't think Python  
benefits from having at least a half-dozen of them. If the energy  
that went into developing reST, epydoc, pydoc, doxygen for Python,  
happydoc, and SAGE-YADMUS had gone into improving any one of them, I  
think the entire Python community would be better off.


> 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.

I'm not sure exactly what you mean by this. We have full examples of  
different applications of FiPy. Those are each in individual files  
where the entire thing is just a big docstring, including doctest  
lines, with a little bit of code at the end to take care of loading  
the doctest lines and running them. Those individual scripts can be  
run on their own (although simply as scripts, not as doctests).  We  
also document the usage of individual methods with specific doctests.  
I can't imagine why I'd want to just run one of them.


More information about the Scipy-dev mailing list