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.
That's fine. I just raised it because I like graphical examples but 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.
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.
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. I've now downloaded FiPy to take a look. I think it's very nicely documented. My impression is that the in-code examples have limited mark-up and just a couple of simple, non-graphical examples. This allows them to be uncluttered and remain comprehensible when getting the docstring interactively. Detailed examples, although heavily marked-up, are in separate modules. I'd be happy if numpy/scipy adopted this approach of limiting and separating the mark-up. The LaTeX source is available. I'd like to know what others think about following FiPy's example. What else needs to be considered? I think that to build a skeleton reference document, the numarray document could be a starting point as its source is available, except it seems, for the LaTeX class file. I couldn't find the Numeric doc source. I'm not sure whether it's OK to just include relevant bits of these, but it looks like it's OK, provided suitable licence stuff and attribution is included. A skeleton based on FiPy's manual and the available numarray LaTeX with a mini-spec for docstrings would be something I could have a go at. Gary R.