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

[John Hunter]

On Sat, Dec 13, 2008 at 8:42 PM, Pauli Virtanen <pav at iki.fi> wrote:

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

It is possible to write doc strings that look one way in the
interactive help, and another way when building the html/pdf.  For
example, in mpl svn, we have a function which builds property tables
for all our artists, so when you see the help for "fill" for example,
you see the kwargs with nice links

  http://matplotlib.sourceforge.net/api/axes_api.html#matplotlib.axes.Axes.fill

but when you say "help fill" from the python shell all the link markup
is left out.  In the fill docstring, we do
        """
        kwargs control the Polygon properties:

        %(Polygon)s

        **Example:**

        .. plot:: mpl_examples/pylab_examples/fill_demo.py

        """

and interpolate the table into %(Polygon)s .  The table is
autogenerated, and will either generate ReST minus the heay link
markup or ReST plus the heavy markup depending on the rc setting

  docstring.hardcopy : True  # set this when you want to generate
hardcopy docstring

Basically, our docstrings are generated using python string
interpolation at runtime so that they look the best for the
environment they are in.  docstring.hardcopy defaults to false, but we
turn it on locally for our doc builds.

JDH