Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOC] napoleon type aliases for generic types not enabled #1229

Open
kandersolar opened this issue May 13, 2021 · 1 comment · May be fixed by #1693
Open

[DOC] napoleon type aliases for generic types not enabled #1229

kandersolar opened this issue May 13, 2021 · 1 comment · May be fixed by #1693

Comments

@kandersolar
Copy link
Member

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).

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_aliases

Describe 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.

@wholmgren
Copy link
Member

Cool feature. #765 is relevant

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants