DOC: Update the docstring for np.around #21853
Conversation
Co-authored-by: Mukulika Pahari <mukulikapahari@gmail.com>, Aparna Bushan <aparna.bushan@auto-grid.com>
This generally seems fine to me (see inline comments) but I don't think it's sufficient to close #19717.
If I understand the issue correctly, the main problem is that users can't find numpy.round in the generated html docs. The fix for this problem would be to add round to the appropriate autosummary so that the stubs are generated correctly; i.e. add "round" to the autosummary in routines.math.rst.
I'd also argue in favor of removing round_ from the list, but that is its own discussion which should be left to a separate PR!
numpy/core/fromnumeric.py
Outdated
| @@ -3243,12 +3243,14 @@ def around(a, decimals=0, out=None): | |||
| See Also | |||
| -------- | |||
| ndarray.round : equivalent method | |||
|
|
|||
| numpy.round_ : equivalent method | |||
There was a problem hiding this comment.
I don't think we should be linking to round_ - users should probably prefer numpy.round, which is literally the same function with a different (less clunky) name.
There was a problem hiding this comment.
Both np.round and np.round_ are backwards-compatibility aliases. Neither should be used, and when they are listed as aliases, we should probably note that whenever they are mentioned. They have equivalent status and should probably both be listed here as disrecommended backwards-compatibility aliases.
IIRC, we originally had numpy.round, but that shadowed the builtin round() when from numpy import * was used (which was common at the time). For backwards compatibility, we renamed it to np.round_ and left np.round as an alias but removed it from the np.__all__ list. Sometime later, we decided that the underscore-appending naming scheme was too clunky for the official preferred versions of such functions and settled on the a prefix (around, amin, amax, etc.).
numpy/core/fromnumeric.py
Outdated
| ceil, fix, floor, rint, trunc | ||
|
|
||
|
|
||
| Notes | ||
| ----- | ||
| np.round is often used as an alias for np.around. |
There was a problem hiding this comment.
Using single backticks will make these terms link to their definitions.
| np.round is often used as an alias for np.around. | |
| `round` is often used as an alias for `around`. |
If you want to be very specific about the namespaces (which may make sense in this case) you can instead use the fully-qualified name, e.g. `numpy.round`.
If you really want to use the np alias (and have the terms not be links), then these should be wrapped in double-backticks so that they are formatted as code, e.g. ``np.round``
|
We should finish this up. @rossbar What remains to be done. I also wonder if we should suggest that |
|
I took the liberty of adding a few final touchups, but LGTM - thanks @InessaPawson & @Mukulikaa ! |
DOC: Add note to clarify relationship between round and around (numpy#21853)
|
@rossbar, thank you for taking care of it! Should I open a discussion about the deprecation of round_ on the mailing list? |
|
@rossbar Do we still want to remove |
Updating the docstring for np.around to address #19717.
Co-authored-by: Mukulika Pahari mukulikapahari@gmail.com, Aparna Bushan aparna.bushan@auto-grid.com