[SciPy-dev] Fwd: [sage-devel] numpy in SAGE, etc.
Jonathan Guyer
guyer at nist.gov
Sat Dec 9 10:03:55 EST 2006
On Dec 9, 2006, at 4:26 AM, Gary Ruben wrote:
> I'm
> concerned about advocating reliance on any separate package, although
> matplotlib has probably gained enough acceptance that it's OK to
> assume
> it will be available on most numpy users' systems.
We actually provide a set of abstraction classes for that reason, and
our examples all just say things like "viewer = fipy.viewers.make
(...)" to return something acceptable as long as at least one of our
supported viewers is installed. Particularly after what we saw at
SciPy'06, though, we're moving toward only supporting matplotlib (at
least for 1D and 2D).
> I was envisaging several small examples in docstrings in the code
> modules with the ability to run any of them interactively. I think
> this
> is how it would be used in SAGE and in ipython.
You can restrict doctests down to one module vs. another, but I don't
know if there's any way to restrict it to only running the tests of a
particular method (although I've never tried), and there's certainly
no mechanism to run only some tests of a method but not others. I
haven't missed that ability, but I can see how other uses might call
for it.
> I've now downloaded FiPy to take a look. I think it's very nicely
> documented.
Thank you.
> My impression is that the in-code examples have limited
> mark-up and just a couple of simple, non-graphical examples.
The *NoiseVariable classes have some graphical examples, but other
than that, we either haven't found the time or the need to do it. I'd
be happy to hear of cases where you think graphics would be helpful
in our API documentation.
If anybody else wants to follow along at home, you can download our
manuals from <http://www.ctcms.nist.gov/fipy/download/> without
having to get the rest of the package. fipy.pdf is the user guide,
with examples. reference.pdf is the API documentation.
> This allows
> them to be uncluttered and remain comprehensible when getting the
> docstring interactively. Detailed examples, although heavily marked-
> up,
> are in separate modules.
We provide a mechanism, via our setup.py script, to strip the markup
if people want to adapt our examples without figuring out how to
write docstring/doctest markup. On the other hand, I've come to
writing all of my research codes in docstring/doctest. The ability to
interlace math and code makes it a lot easier for me to figure out my
codes when I come back to them later and clearer to explain to other
people. There's an emacs mode for writing doctest out there
somewhere, and I've cobbled together some modifications of Alpha's
Python mode that simplify writing doctest; I really need to finish
that up and check it back in to AlphaTcl.
> I'd be happy if numpy/scipy adopted this
> approach of limiting and separating the mark-up. The LaTeX source is
> available.
Be aware that you might have trouble building our docs. We used to
try to ensure that anybody could build it, but eventually decided
that we were more concerned with our ability to produce manuals that
looked the way we want than we were with the rare cases of anybody
else trying to build it. It's not a huge deal, but you'll need a
couple of LaTeX classes and you'll need to adjust your paths to find
our hacked epydoc. Anyway, if you want help, write me directly and
I'll try to get it working for you.
More information about the SciPy-Dev
mailing list