[SciPy-Dev] docstring standard: parameter shape description

Ralf Gommers ralf.gommers@gmail....
Tue Jan 29 14:37:18 CST 2013

On Tue, Jan 29, 2013 at 5:17 AM, Cera, Tim <tim@cerazone.net> wrote:

>>  So, my proposal is now:
>> ------------------------------------------------------------------------------
>> param1 : ndarray, shape <shapespec> [(see text)]
>> as in
>> param1 : ndarray, shape (2, 2+, dim(0+), 4-, 4-6, opt(N)) (see text)
>> in <shapespec>:
>>   the spec reads from the slowest-varying to the fastest-varying dimension
>>   a number means exactly that number of items on that axis
>>   a capital letter (variable) means 1 or more items, for later reference
>>   a number followed by a "+" ("-") means that number or more (fewer) items
>>   a-b, where a and b are numerical sizes, means between a and b items,
>>   dim(dimspec) means the conventions above apply for dimensions instead
>> of items
>>   opt() means this part of the specification is optional
>> shorthands:
>>   0 starting a range means the dimension (or list of dimensions) is
>> optional
>>   "..." is an alias for dim(0+) (any number of dimensions, or none)
> shape(-1)    (couldn't resist)

> But really I don't understand.  This might be useful as a programming
> specification to be parsed to validate parameters, but for documentation?

Same here. The last thing I want is to have a new incomprensible mini-DSL
for shape specification. If you explain it anyway in text, then there's no
point in using this kind of specifier with "dim", "opt" and ranges. If not,
then the reader will have to go look it up in the docstandard, which is
also no good.

> I remember this discussion in the numpy or scipy doc editor.  My memory is
> that the decision was...
> param1 : (N,) array_like
>     This is a 1D array.
> That is why I made the changes that I did.  The problem is that those
> discussions are not searchable and I couldn't find the thread (quickly
> anyway).  Could someone who has some Django experience add the capability
> to search discussions?  Helpful link ->  https://github.com/pv/pydocweb
> Ralf - I appreciate the tedium of going through hundreds of changes and
> deciding should it stay or should it go.  Sorry.  Now, if they were only my
> edits, you could have just accepted them because they were perfect.  :-)

No problem. Keep on doing what you do:)

> Another nice thing would be to have the docstring editor have stronger
> 'linting' capabilities.  It catches some things like long lines, but it
> would be nice to test for more of the docstring standard AND to be able to
> search for failed 'linting' tests - the same way you can search for
> docstring without examples.
> I don't understand the workflow concerning the interaction between the
> code and pydocweb, so this is just talking out my hat, but can't the
> docstrings be edited in a batch (for example using 'sed') and the edited
> docstrings brought into pydocweb?

Any batch editing you can just commit and send a PR for. Then they'll show
up in the doc wiki after merging. Way less overhead.


> I am neutral on Ralf's initial recommendation.  Suggest that should pick
> one way to do it though, so if a change is to be made I think having a
> uniform approach is more readable.
> param1 : array_like
>     Can be any shape...
> param2 : array_like, shape(N,)
>     A 1D array, specified whether ``N`` is used or not.
> param3 : array_like, shape(K,)
>     Another 1D array
> As I was typing out the examples above I realized the `param3` proves my
> point.  If ``K`` is not mentioned then Ralf's initial suggested docstring
> standard would have described the shape of `param3` in the text.  This
> would make the  'param3 : ...' line and 'param1 : ...' line seem to
> indicate the same thing.  You would have to read the text to see the
> difference.  Now, how often does this happen where you have parameters of
> different shapes that would confuse under the proposed standard?  I have no
> idea.
> Kindest regards,
> Tim
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20130129/f3f527b9/attachment.html 

More information about the SciPy-Dev mailing list