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. >
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 [email protected] http://mail.scipy.org/mailman/listinfo/numpy-discussion
