[SciPy-dev] FFT docstrings (was: Scipy Tutorial (and updating it))
Sat Dec 13 13:42:21 CST 2008
Sat, 13 Dec 2008 13:48:51 -0500, jh wrote:
> On Fri, Dec 12, 2008 at 03:19:05PM -0500, firstname.lastname@example.org wrote:
> 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.
More information about the Scipy-dev