[Numpy-discussion] Where to put versionadded
josef.pktd at gmail.com
josef.pktd at gmail.com
Fri Apr 4 16:08:08 EDT 2014
On Fri, Apr 4, 2014 at 3:33 PM, <josef.pktd at gmail.com> wrote:
> 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.
since I like history:
AFAICS:
arraysetops was changed in 1.4
histogram was added in 0.4
corrcoef was added in 0.9.2
numpy 0.9.2 is 8 years old
python 2.1 has soon it's 13th anniversary
Josef
>>>
>>>
>>> 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
More information about the NumPy-Discussion
mailing list