You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Is your feature request related to a problem? Please describe.
I have seen a few cases where folks didn't know how to interpret the generic type description numeric in our docstrings and ended up writing inefficient loop-based code because they didn't understand that numeric implies that the function is vectorized. It's defined on this docs page, but it doesn't seem very discoverable to me (I knew it was in the docs somewhere but still took me a minute to track it down).
Is your feature request related to a problem? Please describe.
I have seen a few cases where folks didn't know how to interpret the generic type description
numeric
in our docstrings and ended up writing inefficient loop-based code because they didn't understand thatnumeric
implies that the function is vectorized. It's defined on this docs page, but it doesn't seem very discoverable to me (I knew it was in the docs somewhere but still took me a minute to track it down).Describe the solution you'd like
Add type aliases so that
numeric
and the other generic descriptors get hyperlinked to their definitions, similar to how intersphinx links types to their docs. Type aliases are a relatively new napoleon feature described here: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_type_aliasesDescribe alternatives you've considered
None, I'm not very imaginative.
Additional context
We would need to bump our sphinx version from 3.1.2 to >=3.2 to use type aliases.
Side note, that docs page linked above lists some other interesting new-ish napoleon features like custom docstring sections... food for thought.
The text was updated successfully, but these errors were encountered: