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. > > > 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. Cheers, Matthew _______________________________________________ NumPy-Discussion mailing list [email protected] http://mail.scipy.org/mailman/listinfo/numpy-discussion
