[SciPy-Dev] Documenting distributions, advice?

josef.pktd@gmai... josef.pktd@gmai...
Tue Jul 6 15:21:47 CDT 2010

On Tue, Jul 6, 2010 at 3:24 PM, Ralf Gommers
<ralf.gommers@googlemail.com> wrote:
> On Wed, Jul 7, 2010 at 2:59 AM, David Goldsmith <d.l.goldsmith@gmail.com>
> wrote:
>> On Tue, Jul 6, 2010 at 11:31 AM, Pauli Virtanen <pav@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.

 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.


> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev

More information about the SciPy-Dev mailing list