[SciPy-dev] ndimage - docfiller and output_type

[josef.pktd at gmail.com]

On Thu, Oct 29, 2009 at 5:28 AM, Ralf Gommers
<ralf.gommers at googlemail.com> wrote:
>
>
> On Wed, Oct 28, 2009 at 11:15 PM, <josef.pktd at gmail.com> wrote:
>>
>> While I was looking at the docstrings for the distributions, I
>> thought, that the list of
>> parameters is a bit misleading. They are listed as if they were the
>> parameters
>> for the constructor or for calling the instance. Example
>>
>>
>> http://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.maxwell.html#scipy.stats.maxwell
>>
>> The class is already instantiated, and __call__ takes (<shapes>, loc
>> and scale) as parameters.
>
> Confusing right now, I agree. Maybe the heading should be changed to
> "Instance call parameters" or similar, or no heading at and just explain it
> in text.
>
>>
>> Maybe that's the reason that most user examples, I have seen, use the
>> frozen distribution. The
>> distribution instance is documented as if it were a class.
>>
> The whole explanation on frozen distributions, and RV objects, is
> confusing.  My impression is that you would rarely need this (is that
> right?) so it should probably be moved to a Notes section.
>
>> However it looks different in the doc editor
>> http://docs.scipy.org/scipy/docs/scipy.stats.maxwell/#scipy-stats-maxwell
>>
> This are reordered a bit. They really should look the same. For now let's
> only look at the doc editor, and if there are differences consider it a bug
> in the doc build process.
>>
>> In the current generated docs, I don't see the methods of the
>> individual distributions listed,
>> e.g. norm.cdf. Methods only have the generic docstring (?), but method
>> doc inheritance
>> doesn't work for some reason?
>
> Do you mean that you expect to see the longer docstring of rv_continuous.cdf
> in the Methods section of the instance docstring? It does not work like that
> for any class. For normal classes public methods would have their own
> docstring and the method name in the class docstring turns into a link. That
> should ideally be the case here as well, maxwell.cdf should link to
> http://docs.scipy.org/scipy/docs/scipy.stats.distributions.rv_continuous.cdf/
>
>
>>
>> (I'm starting to get too confused about which version of the docs, I'm
>> looking at.)
>>
>> Just another thought:
>>
>> The instance/class docstrings are currently missing a link to the
>> methods of the distributions.
>> If the methods can be linked to from the distributions, then I think
>> it would be nicer to have only a minimal (generic) descriptions of the
>> methods in the "class"/instance docstring for the individual
>> distributions and at see also to the generic distribution class which
>> could have some more explicit information.
>
> Ah yes, see what I typed above.
>
>>
>> If the "boiler plate" doc
>> in the instance docstring shrinks, we could add over time some real,
>> distributions specific examples, if we have the templating structure
>> in place without overloading the docstring.
>
> Exactly, this is what I'm hoping to achieve.
>
>>
>> Currently the only templated but correctly adjusted signature for the
>> methods is in the class/instance docstring, so maybe this doesn't
>> work.
>>
> A correct signature on a method page that is linked will not be possible I
> think. Method signature should remain in the instance docstring.
>
>
>> Josef
>>
>> (It's pretty tiring to figure out or keep track of how help(obj),
>> print  obj.__doc__, ipython, the doceditor and sphinx are generating
>> and interpreting generated docstrings.)
>>
> With your name.__class__.__doc__ fix they all look pretty similar. That
> said, I consider html and ipython most important and help() a distant third.
> (How can you even live without readline?).

I have to look at this again next week when I have a bit more time.

I don't mind the boiler plate code in the individual distributions anymore,
if we can improve the docs for the distributions this way. You could try
it out on a few distributions to avoid having to edit 90 templates if there
are any changes.

Just a quick summary (or wishlist), I agree with most/all of your proposals

* more informative (developer) docstrings for generic rv_continuous
  rv_discrete
* keep individual signature of methods in distribution class docstring
  and clarify role of parameters and __call__ for frozen distribution;
  get links to generic method description
* two ways of creating doc string (?)
  - generically generated for distributions nobody wants to edit,
    including minimal templating for non-scipy subclasses.
  - docstrings with individualized parts, where someone can
    edit at least notes, example and reference sections
* SeeAlso to generic distribution class description and link
  to distribution in tutorial (?)
  Can we have links to numpy docs for random, but this wouldn't
  work in a local html or htmlhelp with different files?
  numpy.random has already a lot more descriptions for the
  individual distributions.
* attach docs to __class__ instead of instance
* ...?

Two more issues:

How much boiler plate do I have to edit if I add a new method to the
generic classes, rv_continuous, rv_discrete
or edit an existing one?

Maybe it would be good to add an attribute description for a, b,
numargs and shape to the class docstrings.
In the generic classes, I would also like to document other (and some
private) methods. Currently starting with underline is not a good
indication for whether the method is considered private. Several
private methods are missing the underline, and
many of the private methods are useful (with some restrictions).

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

and can we induce editors to edit the notes in the distribution
reference (in tutorial) instead of blowing up the
notes section in the actual docstring. (following Pierre's
suggestions). Is there a page limit on the size of the docs?


I will be very glad, when we get proper documentation for classes in scipy.

Thanks,

Josef

(no readline for me, it's to unixy. I use htmlhelp for the docs that
are up-to-date, doceditor for missing or messy docs,  and Idle,
Spyder, Eclipse, or a plain windows command shell, when I don't want
any interference from magic or background processes of the editor.)


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