[SciPy-dev] FFT docstrings (was: Scipy Tutorial (and updating it))

[Pauli Virtanen]

Sat, 13 Dec 2008 13:48:51 -0500, jh wrote:
> On Fri, Dec 12, 2008 at 03:19:05PM -0500, jh at physics.ucf.edu wrote:
[clip]
> Gael responded:
>> Yes, I was thinking similarly. This is exactly why I brought up the
>> question about plotting.
> 
> We avoid plots when possible, of course, but I think that if ever there
> were a case for a line plot in numpy, it would be fft.  The constraints
> are that we want a plot in the docs but can't have one in the most basic
> doc reader, help().  A compromise might be to put it in the package
> docstring and not the routine docstrings.  We might also include the
> full filename of the plot, so someone working in text could view the
> plot separately.

I'd think there are plenty of possibilities for plots in Numpy 
documentation. For example, polyfit, etc. I'd also want to avoid putting 
any file names to the docstrings, as the base directory for these is 
ambiguous, and having a file name in the documentation is not really 
helpful for the reader. Moreover, filenames may easily clash, eg. 
plot-1.jpg, plot-2.jpg, etc.

Instead, we can put in code that produces the plot -- this helps both 
people reading the documentation via help (they can reproduce the plot 
themselves), and those reading the HTML or PDF versions (they can see 
both the code and the output). So, I don't think there's any special need 
to avoid plots. The code supporting plots in the documentation already 
exists (borrowed from matplotlib), we only need to decide how we want to 
use the feature. There's a thread on the numpy-discussion list about this.

> Looking ahead, would it be possible to get Python to use a module's
> help() method if it exists?  Then we could replace help() with a
> full-functioning reader that defaults to the current help() behavior but
> could be configured by a state variable to run a browser for the PDF or
> HTML docs.  I assume this would require a PEP and providing some code.

The help command can be overridden by replacing __builtin__.help, but I 
don't think doing this kind of monkeypatching is the proper thing to do 
on "import numpy". Rather, there could be a separate function that opens 
the correct point in the documentation in the browser. But I'm unsure how 
big convenience this actually is, as it's pretty quick to look up 
documentation for functions and modules using search in the HTML/PDF docs.

-- 
Pauli Virtanen