[SciPy-dev] ndimage - docfiller and output_type

[Ralf Gommers]

On Thu, Oct 29, 2009 at 5:12 PM, <josef.pktd at gmail.com> wrote:

> >>
> >> * attach docs to __class__ instead of instance
> >
> > I was not paying attention there. Assigning to __class__.__doc__ only
> works
> > for old-style classes. rv_generic inherits from object, so it does not
> work
> > then. If this is important to you to fix help() you can always convert to
> > old-style classes. I had a quick look, and I don't think any of the
> > old-style / new-style differences matter for stats.distributions.
>
> I thought that's what you did earlier. I will check again.
>
> Yes but then I forgot I removed `object`. It seems fine, but it would be a
little impolite from me to convert all classes to old-style without asking.
Also, in Python 3 it will stop working because there are no old-style
classes anymore.

>
> >
> >
> >> Longer term question:
> >>
> >> How much information do we want in the docs about individual
> >> distributions. e.g. compared to
> >>
> >>
> >>
> http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/maxcdf.htm
> >> with some duplication in
> >>
> >>
> http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/maxpdf.htm
> >> and
> >>
> >>
> http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/maxppf.htm
> >>
> > That seems a bit too much right? One page for each distribution method =
> 90
> > dist * 6 methods = many hundreds of pages.
>
> For us it should be more like one page description per distribution,
> makes 90 pages.
> We could add the scripts for the graphs, instead of the actual graphs,
> as it is done in the current class docstring.
>

That seems reasonable.

>
> The links are a bit difficult to see, in the second paragraph
>
>
> http://docs.scipy.org/scipy/docs/scipy-docs/tutorial/stats/continuous.rst/#continuous-random-variables
>
> http://docs.scipy.org/scipy/docs/scipy-docs/tutorial/stats/discrete.rst/#discrete-random-variables
>
> I think it was Gokhan Sever who converted the lynx docs of Travis to
> rst. The first is currently a huge page that takes a long time to
> load. It will eventually need to be broken up.
>

Ah very nice, I had not seen that page before. The docstrings should link
there. It's mostly math anyway and would not work well in the docstrings
themselves.

>
> >
> > I like the numpy.random pages, for example
> >
> http://docs.scipy.org/numpy/docs/numpy.random.mtrand.RandomState.standard_t/
> > Maybe one or two paragraphs more, that should be enough for pretty much
> any
> > distribution function, or not?
>
> Yes, the notes in random are good, in scipy we have more formulas for
> the properties of the distributions, that can be calculated using the
> distribution methods.
> I don't know whether we want to copy or link to the description in
> numpy.random.
>
> Linking is better I think.


> >
> > No idea about a page limit, but if you plan on writing more than a page
> and
> > a half per distribution, you have enough material for a book.....
>
> Some packages, I have seen, have an almost book length description of
> the distributions. The one, I was reading more, was, however,
> distributed as a separate pdf file.
>
> It may indeed be a good idea to have a separate pdf of stats docs. The
whole scipy reference guide pdf is already 710 pages and will eventually be
a couple of times larger than that.


> (When you are ready to do the next group, the docs for classes in
> interpolate are bothering me for a long time, and several more once I
> see a clear pattern how classes and modules should be documented.)
>
> Well the scipy doc editor says 5% worked on, 95% still untouched, so pretty
much all of them still bother me:)

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091030/1581d577/attachment.html>