[Numpy-discussion] Where to put versionadded

Charles R Harris charlesr.harris at gmail.com
Fri Apr 4 14:54:47 EDT 2014


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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20140404/509adbbe/attachment.html>


More information about the NumPy-Discussion mailing list