[SciPy-Dev] Documenting distributions, advice?

[Ralf Gommers]

On Tue, Jul 6, 2010 at 11:42 PM, Skipper Seabold <jsseabold at gmail.com>wrote:

> On Tue, Jul 6, 2010 at 11:29 AM, Matthew Brett <matthew.brett at gmail.com>
> wrote:
> > Hi,
> >
> > I was just playing with the Gamma distribution (sicpy.stats.gamma) and
> > I found it hard to work out how the distribution related to the
> > standard sources on the topic.   I think I'm getting there now, but
> > I'm wondering whether there is anywhere some advice on documenting
> > scipy.stats.distributions?  For example, it looks as if there is only
> > the 'extradoc' docstring addition for any specific distribution - is
> > that right?
> >
> > Thanks a lot,
> >
> > Matthew
>
> After spending the last few days with the distributions trying to fix
> one thing, I am also wondering about this and other questions with
> respect to the distributions (more to come later...).
>
> At the risk of telling you things you already know, I usually start here:
>
> <http://docs.scipy.org/scipy/docs/scipy-docs/tutorial/stats.rst/#stats>
>
> Then click on say 'continuous distributions' link towards the top to
> see the LaTeX math
>
>
> http://docs.scipy.org/scipy/docs/scipy-docs/tutorial/stats/continuous.rst/#continuous-random-variables
>
> Then I go back and forth between Wikipedia to back out what our
> parameters mean since they are often not standard (with Wikipedia
> being standard, of course...).
>
> I am willing to get involved in the docs marathon with the stats
> stuff.  Josef, Ralf, others, I know you have worked on this issue much
> more than I.  Any thoughts for streamlining things and making the
> distributions a little easier to work with?  I, for one, am willing to
> give up some of the "autodoc'ing" (and do the work that this means) if
> it would improve anything from a user or developer standpoint.  Maybe
> we can add a notes section, since there is a note not to use extradoc
> (?), for noting things like differing parameterizations of the
> distributions in the literature.
>
> After the recent changes to distribution docstrings this kind of thing is
easy to achieve. To add a notes section you would do (for gamma_gen for
example):
    """A gamma function continuous random variable.

    %(before_notes)s

    Notes
    -----
    This is some note specific to gamma which explains bla bla....

    %(example)s
    """

In the same way you can add a custom example, references, change a parameter
description, etc. And no need to give up "autodoc'ing" for the standard
parts. The parts of the default docstring available for string substitution
are available in distributions.docdict.

Note that extradoc is still available for backwards compatibility reasons
and should not be used anymore. Eventually everything in extradoc should
migrate over to the new system.

If you write custom docstrings like this, just check they are processed
without error in the interpreter, then commit to svn (or submit a git branch
/ patch). The doc wiki is not aware of those string substitutions, just as
it wasn't aware of extradoc before, and is therefore not very useful in this
case. In the wiki distributions are marked as unimportant, which is fine.

If you find any glitches or things to improve please let me know.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100707/a217b85f/attachment.html>