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

Jarrod Millman millman@berkeley....
Sun Dec 14 14:04:44 CST 2008

On Sat, Dec 13, 2008 at 11:42 AM, Pauli Virtanen <pav@iki.fi> wrote:
> 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.

I agree.  We should avoid filenames (more trouble than its worth).  I
also like the idea of potentially including plot-generating code as
long as we don't include copies of the plots/image.  Including
image-generating docstrings (but not copies of the images) would
provide several advantages:
  - a mini-tutorial on how to plot the results or generate images
using the NumPy/SciPy functionality
  - allow users to quickly generate their own plots (by providing them
with code) if they are interested in exploring
  - be used to generate figures in out HTML/PDF documentation
We should be judicious in our use of image-generating docstrings,
because we need to avoid cluttering up the docstrings to the point
they aren't helpful anymore.  I would also be happy adopting some
rule-of-thumb that image-generating docstrings have to be no more than
XX number of lines.

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

I agree that we should avoid monkeypatching __builtin__.help.  We
should avoid adding functions to open up a web-browser.

Jarrod Millman
Computational Infrastructure for Research Labs
10 Giannini Hall, UC Berkeley
phone: 510.643.4014

More information about the Scipy-dev mailing list