[SciPy-Dev] docstring standard: parameter shape description

Cera, Tim tim@cerazone....
Mon Jan 28 22:17:56 CST 2013


> 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,
> INCLUSIVE
>   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?

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

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?

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20130128/f9988c63/attachment-0001.html 


More information about the SciPy-Dev mailing list