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.