[SciPy-Dev] scipy.stats documentation

[nicky van foreest]

> Yes that looks good to me.
> a few problems:
> in most cases we have the pdf currently in the docs which is, I guess,
> more familiar to most users.

Ok. I agree that sticking to the pdf is best.

> I'm not sure having 1./scale in front and (x-loc)/scale inside makes
> the pdf easier to read or understand, but it's more explicit.

I am also in doubt about what would be a good generic solution. The
doc string for, for example, the gamma distribution will not become
particularly easy to read, lots of x's... On the other hand, as
Skipper points out below, I have the same problem as him when I want
to use a distribution: I want to rely on the documentation, and not
necessarily first check wikipedia, do some checking, and so on. I'll
think about it a bit more.

> If someone is going through individual distributions, this would be
> very good. (My initial worry a few years ago was that it will be
> difficult to maintain 90 individual docstrings.)

Sure. However, I can start with three or four, and slowly expand.

>> Many of these points seem, at least to me, too minor to raise a
>> ticket, or am I mistaken here?
>
> no individual tickets are necessary.

Hold on. I suppose you mean with  "no" that I am mistaken, and that
tickets are necessary.

> the distribution docstrings are a bit trickier:
> don't edit the generated docstring of the instance, e.g.
> http://docs.scipy.org/scipy/docs/scipy.stats.expon/edit/
> I think that would create a mess

I inferred that the doc-strings in distributions.py should be edited,
and that the reference documentation is automatically created from
these doc-strings. Hence, I intended to change distributions.py. If
this is wrong, let me know.