On Fri, Apr 4, 2014 at 3:33 PM, <[email protected]> wrote: > On Fri, Apr 4, 2014 at 3:07 PM, Matthew Brett <[email protected]> wrote: >> Hi, >> >> On Fri, Apr 4, 2014 at 11:54 AM, Charles R Harris >> <[email protected]> wrote: >>> >>> >>> >>> On Fri, Apr 4, 2014 at 12:48 PM, <[email protected]> wrote: >>>> >>>> On Fri, Apr 4, 2014 at 2:12 PM, Charles R Harris >>>> <[email protected]> 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 >> [email protected] >> http://mail.scipy.org/mailman/listinfo/numpy-discussion _______________________________________________ NumPy-Discussion mailing list [email protected] http://mail.scipy.org/mailman/listinfo/numpy-discussion
