[SciPy-dev] Fwd: [sage-devel] numpy in SAGE, etc.
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
> anything fancier than plain docstrings.
> The other existing options seem to be (from a brief look)
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
> 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