On Fri, Apr 4, 2014 at 3:07 PM, Matthew Brett <matthew.br...@gmail.com> wrote: > Hi, > > On Fri, Apr 4, 2014 at 11:54 AM, Charles R Harris > <charlesr.har...@gmail.com> wrote: >> >> >> >> On Fri, Apr 4, 2014 at 12:48 PM, <josef.p...@gmail.com> wrote: >>> >>> On Fri, Apr 4, 2014 at 2:12 PM, Charles R Harris >>> <charlesr.har...@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. > > 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@scipy.org > http://mail.scipy.org/mailman/listinfo/numpy-discussion _______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion