On Apr 4, 2014 8:54 PM, "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. > > Chuck > > > _______________________________________________ > NumPy-Discussion mailing list > [email protected] > http://mail.scipy.org/mailman/listinfo/numpy-discussion >
My user perspective: I am developing a tool whose main use is to run on my computer, so I prefer to run the newest and sweetest version of the libraries, and I this report the minimum versions. But it would be good if I could grep my code, see what numpy functions are being used and infer a probable minimum version required. If other libraries follow similar conventions, and one does not do metaprogramming or other fancy things, it is relatively easy to get automatically.
_______________________________________________ NumPy-Discussion mailing list [email protected] http://mail.scipy.org/mailman/listinfo/numpy-discussion
