[SciPy-Dev] Documenting distributions, advice?
Tue Jul 6 16:04:23 CDT 2010
On Tue, Jul 6, 2010 at 1:21 PM, <firstname.lastname@example.org> wrote:
> On Tue, Jul 6, 2010 at 3:24 PM, Ralf Gommers
> <email@example.com> wrote:
> > On Wed, Jul 7, 2010 at 2:59 AM, David Goldsmith <firstname.lastname@example.org
> > wrote:
> >> On Tue, Jul 6, 2010 at 11:31 AM, Pauli Virtanen <email@example.com> 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
> >>> > still prefer people to leave these alone for now?
> >>> I think this only concerns the doc editor.
> >> Here's the thread:
> >> 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
> >> conservative in interpreting his request, i.e., refrain from touching
> >> '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.
> 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.
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.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the SciPy-Dev