[SciPy-Dev] Documenting distributions, advice?

[David Goldsmith]

On Tue, Jul 6, 2010 at 1:21 PM, <josef.pktd at gmail.com> wrote:

> On Tue, Jul 6, 2010 at 3:24 PM, Ralf Gommers
> <ralf.gommers at googlemail.com> wrote:
> >
> >
> > On Wed, Jul 7, 2010 at 2:59 AM, David Goldsmith <d.l.goldsmith at gmail.com
> >
> > wrote:
> >>
> >> On Tue, Jul 6, 2010 at 11:31 AM, Pauli Virtanen <pav at iki.fi> wrote:
> >>>
> >>> Tue, 06 Jul 2010 09:08:35 -0700, David Goldsmith wrote:
> >>> > At Josef's request, I marked all the distributions unimportant - he
> >>> > asked that they not be worked on for the time being.  Josef, would
> you
> >>> > still prefer people to leave these alone for now?
> >>>
> >>> I think this only concerns the doc editor.
> >>
> >> Here's the thread:
> >>
> >>
> >>
> http://article.gmane.org/gmane.comp.python.scientific.devel/13298/match=josef+may+25+2010
> >>
> >> At best, IMO, it is unclear what Josef meant vis-a-vis not editing the
> >> distribution docstrings in the Wiki vs. at all; I would ask that people
> be
> >> conservative in interpreting his request, i.e., refrain from touching
> them,
> >> 'til he has had a chance to clarify his intent.
> >>
> > Pauli got it right, and the intent is clear. Improvements are welcome of
> > course.
> >
> > Cheers,
> > Ralf
>
> (Sorry for any delays, I'm in a beach and family time zone)
>
> Essentially, I'm not a fan of docstrings and examples that don't add
> much information to the generic docs but require maintenance. (e.g
> redoing all examples if implementation detals or precision changes)
> Although, now that several users/developers are looking at
> stats.distributions maybe that won't be my problem anymore.
>
> For general explanations to the distributions, I think expanding on
> the formulas/definitions in scipy.stats.tutorial (splitting up the
> pages) would be more useful than making the distribution class
> docstring very long (argument by Pierre).
>
> Note I'm usually just using
> >>> np.source(stats.distributions.gamma_gen)
> >>> print stats.gamma.extradoc
>
> The rest is just repetition that I never read. "print
> stats.gamma.__doc__" is too much noise.
>
> Feel free to add any information that makes it more easily accessible,
> especially if Ralf thinks that the template system works without too
> much problem.
>
> David,
>  I think we should stay with "unimportant" for now, mainly because the
> basic docstrings are there, and I don't think the distributions should
> be advertised as interesting edits (compared to all the other work
> that is necessary in the scipy docs), and I would like to move slowly
> until a pattern of enhanced distributions docs is established.
>
> Josef
>

OK, perhaps we don't understand the issues the same way, but I'm still
getting mixed signals; Ralf, on the other hand, seems to feel he and Pauli
clearly understand what you have in mind, so I'll happily defer to them.

DG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100706/e8de639e/attachment.html>