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. Josef > > Chuck > > > > _______________________________________________ > 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