[Numpy-discussion] Where to put versionadded

[josef.pktd at gmail.com]

On Fri, Apr 4, 2014 at 3:07 PM, Matthew Brett <matthew.brett at gmail.com> wrote:
> Hi,
>
> On Fri, Apr 4, 2014 at 11:54 AM, Charles R Harris
> <charlesr.harris at gmail.com> wrote:
>>
>>
>>
>> On Fri, Apr 4, 2014 at 12:48 PM, <josef.pktd at gmail.com> wrote:
>>>
>>> On Fri, Apr 4, 2014 at 2:12 PM, Charles R Harris
>>> <charlesr.harris at gmail.com> wrote:
>>> > Hi All,
>>> >
>>> > Currently there are several placements of the '.. versionadded::'
>>> > directive
>>> > and I'd like to settle
>>> > on a proper style for consistency. There are two occasions on which it
>>> > is
>>> > used, first, when a new function or class is added and second, when a
>>> > new
>>> > keyword is added to an existing function or method. The options are as
>>> > follows.
>>> >
>>> > New Function
>>> >
>>> > 1) Originally, the directive was added in the notes section.
>>> >
>>> > Notes
>>> > -----
>>> > .. versionadded:: 1.5.0
>>> >
>>> >  2) Alternatively, it is placed after the extended summary.
>>> >
>>> > blah, blah
>>> >
>>> > ..versionadded:: 1.5.0
>>> >
>>> > Between these two, I vote for 2) because the version is easily found
>>> > when
>>> > reading the documentation either in a terminal or rendered into HTML.
>>> >
>>> > New Parameter
>>> >
>>> > 1) It is placed before the parameter description
>>> >
>>> > newoption : int, optional
>>> >     .. versionadded:: 1.5.0
>>> >     blah.
>>> >
>>> > 2) It is placed after the parameter description.
>>> >
>>> > newoption : int, optional
>>> >     blah.
>>> >
>>> >     .. versionadded:: 1.5.0
>>> >
>>> > Both of these render correctly, but the first is more compact while the
>>> > second puts the version
>>> > after the description where it doesn't interrupt the reading. I'm
>>> > tending
>>> > towards 1) on account of its compactness.
>>> >
>>> > Thoughts?
>>>
>>> I'm in favor of putting them only in the Notes section.
>>>
>>> Most of the time they are not "crucial" information and it's
>>> distracting.  I usually only look for them when I'm working explicitly
>>> across several numpy versions.
>>>
>>> like in python: versionadded 2.1 is only interesting for historians.
>>
>>
>> I find the opposite to be true. Because numpy needs maintain compatibility
>> with a number python versions, I often check the python documentation to see
>> in which version a function was added.
>
> I agree; versionadded 2.1 is not likely interesting but versionadded
> 2.7 is very interesting.

That's true, but it's a mess for maintainers because we support now 5
python versions.

numpy doesn't have a long history of versionadded yet, I didn't find
anything for 1.3 in a quick search.
statsmodels has now numpy 1.6 as minimum requirement and I'm
interested in the features that become available with a minimum
version increase.
Once I know what I'm allowed to use, I only care about the "real"
documentation, "How does einsum really work?".

But as a numpy user, I was never really interested in the information
that arraysetops where enhanced and renamed in numpy 1.x (x=?<4), or
that take was added in 0.y, ...  Even the first part of polynomial is
already in 1.4
(It might just make me feel old if I remember when it was changed.)

versionadded is not very distracting in the html rendering, so I'm
just +0.1 on Notes.

Josef

>
> Cheers,
>
> Matthew
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion