[SciPy-dev] ndimage - docfiller and output_type

[josef.pktd at gmail.com]

On Mon, Nov 16, 2009 at 11:50 AM, Ralf Gommers
<ralf.gommers at googlemail.com> wrote:
> Thanks for the review Josef.
>
> On Mon, Nov 16, 2009 at 3:52 AM, <josef.pktd at gmail.com> wrote:
>>
>> Thanks, I took your version from github. Since there are many changes,
>> including cosmetic, I didn't go over all of them. I compared several
>> docstrings of the old and the new version, and overall it seems to work
>> very well.
>>
>> The main mistake currently is that the generic docstring for discrete is
>> the same as the one for the continuous distributions, e.g.
>>
>> print stats.poisson.__doc__
>>
>> discrete distributions don't have a scale argument, and don't have a pdf
>> method, instead of pdf, discrete distributions have a pmf probability mass
>> function.
>
> fixed.
>>
>> Second, the generic class docstrings are pretty empty, e.g. they don't
>> have
>> the list of methods.
>>
>> print stats.distributions.rv_discrete.__doc__
>> print stats.distributions.rv_continuous.__doc__
>>
> What is missing is mainly info on how to subclass those two classes. I was
> hoping you would fill in the blanks there since you know much more about how
> this works than I do.
>
> I do not think simply listing all methods is helpful, and that is also
> explicitly discouraged in the doc standard.

see below

>
>>
>> taste questions:
>> I don't think I like the formulas in the methods, e.g. print
>> stats.wald.__doc__
>> I think, formulas from the extradocs should go into a notes section.
>
> That does look a little better, done.
>>
>> I would also prefer to keep extradoc for now, even if it is not used
>> anymore for the docstrings, just because I'm very used to using it. We
>> can drop them later once the new system is fully working.
>
> Sure, done.
>>
>> Given that there is more flexibility with the new system, I would
>> prefer to put the extradoc information into a notes section instead of
>> tucking them on at the end in the default template, if possible.
>>
> Possible and done, looks much better now.
>
>>
>> Why did you special case before and after pdf?
>
> Because the typical extradoc contains only info on the pdf. That info now
> goes into Notes, so I removed before_pdf and after_pdf, and added
> before_notes instead.
>>
>> Also, I think it would be better making the framework changes separate
>> from any changes to the content, e.g rv_continuous, rv_discrete.
>
> I'm not 100% sure what you mean here.

I meant keep the old docstring content of rv_continuous, rv_discrete and
edit the changes when I or someone has time to rewrite them.

In general it's better to have single purpose changesets, to keep track of
changes more easily, than making only partially related changes at the
same time.

>
>> If everything works, we can edit and review changes to the content in the
>> doc editor.
>
> Yes, that would be ideal. It won't work just yet, but the next step is
> indeed to get the doc editor to handle this intelligently.
>>
>> Sorry for the delay in the review, I've been busy and I have problems
>> keeping up with the C changes in numpy and scipy.
>
> No problem. I've had a few problems compiling things as well.
>
>>
>> (I only commented on the parts I didn't like so much, because the rest
>> is a good improvement.)
>>
>
> I updated both the patch in ticket 1055 and the code on github. If you're
> happy with the changes, can you please commit them?

I will try to do this tonight.
Did you try to rebuild the sphinx html docs to see whether they are
affected by the changes?

Thanks,

Josef

>
> Cheers,
> Ralf
>
>
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>