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

[Gary Ruben]

> 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.