[SciPy-dev] ndimage - docfiller and output_type

[josef.pktd at gmail.com]

On Wed, Oct 28, 2009 at 5:00 PM,  <josef.pktd at gmail.com> wrote:
> On Wed, Oct 28, 2009 at 4:16 PM, Ralf Gommers
> <ralf.gommers at googlemail.com> wrote:
>>
>>
>> On Wed, Oct 28, 2009 at 8:34 PM, <josef.pktd at gmail.com> wrote:
>>>
>>> On Wed, Oct 28, 2009 at 2:07 PM, Pauli Virtanen <pav+sp at iki.fi> wrote:
>>> > Wed, 28 Oct 2009 11:13:10 -0400, josef.pktd wrote:
>>> > [clip]
>>> >> No, I like the current system where we don't have any boiler plate in
>>> >> the individual distributions. Following your maxwell example, we would
>>> >> get a lot of repetition of template code in the individual
>>> >> distributions.
>>> >
>>> > Then, I'd suggest just adding
>>> >
>>> >        %(info)s
>>> >
>>> > or so, that will be expanded to the full boilerplate information block.
>>> > Then, only this would be repeated in each distribution docstring -- not
>>> > too bad.
>>>
>>> If you can do it with minimal code/text duplication, then any way is fine
>>> with me.
>>>
>> Okay, I'll come up with a patch with as little duplication as possible (one
>> line per distribution).
>>
>>>
>>> >
>>> > It is clearer and cleaner if the distribution docstring is a template,
>>> > resides in the class docstring, and the final product is assembled by
>>> > substitution rather than by concatenating magically generated parts.
>>> > (Think, for example -- why are HTML templating languages so popular, as
>>> > opposed to just concatenating blocks of HTML code?)
>>>
>>> The last time I looked at mako, it allowed full inheritance and backward
>>> (?)
>>> substitution in the templates.
>>>
>>> I don't see how template inheritance would work with simple string
>>> substitution, but you are the experts for the numpy/scipy documentation
>>> system.
>>
>> Inheritance is the wrong word. The idea is to build up a docstring from
>> smaller pieces, instead of starting with one big template and then trying to
>> change it. In the default (simplest) case, you build up a string in the
>> module scope, only substitute <shapes> for each distribution, and assign it
>> to __doc__.
>>
>> Cheers,
>> Ralf
>
> I like your initially proposed solution, because it allows both ways, either
> full generic template (for distributions that nobody looks at), or following
> the maxwell pattern for the distributions, where someone would want to
> add individualized information.
>
> One other advantage of the generic docstring is that it is easy to create new
> classes outside of scipy by subclassing rv_continuous and have the docstring
> generated the same way as distribution in scipy.
>
> But even having your basic template is not really a problem, it's mainly
> the numpy docstring standard and the template is not something we would
> have to edit often.
> (It would still double the lines of code for many distributions).
>
> I still like to keep name and (maybe) longname since they are used in
> programs, if I remember correctly.
> Personally, I like extradoc, that's the only really interesting information
> about a distribution that I look at (besides dist.a and dist.b and dist.shape.)
> and I don't have to scroll through the boiler plate docstring to read it.
>
> (In general, I think the class should get the default constructor information
> in the __init__ method instead of in the instantiation.)
>
> Josef
>

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

However it looks different in the doc editor
http://docs.scipy.org/scipy/docs/scipy.stats.maxwell/#scipy-stats-maxwell


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?
(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. 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.
Currently the only templated but correctly adjusted signature for the
methods is in the class/instance docstring, so maybe this doesn't
work.

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


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