[SciPy-dev] ndimage - docfiller and output_type

[Ralf Gommers]

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?).

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