[Numpy-discussion] Where to put versionadded

[josef.pktd at gmail.com]

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.

Josef

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