Skip to content

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

Open
@kandersolar

Description

@kandersolar

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions