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

[Jonathan Guyer]

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.