[Numpy-discussion] Where to put versionadded

[Daπid]

On Apr 4, 2014 8:54 PM, "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.
>
> Chuck
>
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>

My user perspective: I am developing a tool whose main use is to run on my
computer, so I prefer to run the newest and sweetest version of the
libraries, and I this report the minimum versions. But it would be good if
I could grep my code, see what numpy functions are being used and infer a
probable minimum version required.

If other libraries follow similar conventions, and one does not do
metaprogramming or other fancy things, it is relatively easy to get
automatically.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20140405/a2a938fc/attachment.html>