[SciPy-Dev] scipy.stats documentation

[josef.pktd at gmail.com]

On Mon, May 7, 2012 at 4:25 PM, nicky van foreest <vanforeest at gmail.com> wrote:
>> 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.

"no" as in "individual tickets are *not* necessary"
(or as in "I would prefer not to see any individual tickets if we can
do it wholesale in a pull request")
(or as in "a ticket to fix a missing comma has too much overhead")

I like tickets for bugs, because that leaves a better (electronic) paper trail.

explicit enough, this time :)

Josef

>
>> 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.
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev