[Numpy-discussion] Where to put versionadded
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? Chuck ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Where to put versionadded
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
Re: [Numpy-discussion] Where to put versionadded
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. Chuck ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Where to put versionadded
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. Cheers, Matthew ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Where to put versionadded
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
Re: [Numpy-discussion] Where to put versionadded
On Fri, Apr 4, 2014 at 3:33 PM, josef.p...@gmail.com wrote: 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. since I like history: AFAICS: arraysetops was changed in 1.4 histogram was added in 0.4 corrcoef was added in 0.9.2 numpy 0.9.2 is 8 years old python 2.1 has soon it's 13th anniversary Josef 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
Re: [Numpy-discussion] Where to put versionadded
On Apr 4, 2014 8:54 PM, 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. Chuck ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org 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 NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
