[SciPy-dev] FFT docstrings (was: Scipy Tutorial (and updating it))
Sun Dec 14 14:04:44 CST 2008
On Sat, Dec 13, 2008 at 11:42 AM, Pauli Virtanen <email@example.com> 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.
Computational Infrastructure for Research Labs
10 Giannini Hall, UC Berkeley
More information about the Scipy-dev