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

Turn off documentation type hints #4510

Merged
merged 1 commit into from
Jan 19, 2022
Merged

Conversation

rcomer
Copy link
Member

@rcomer rcomer commented Jan 18, 2022

🚀 Pull Request

Description

From #4383 (comment) and replies, there seems to be a consensus that we don't want to display type annotations in the docs. There are not many examples in Iris so far, but for recombine_submeshes this PR turns

with_type_hint
into
without_type_hint


Consult Iris pull request check list

@rcomer rcomer changed the title Turn off documenation type hints Turn off documentation type hints Jan 18, 2022
@bjlittle bjlittle self-requested a review January 19, 2022 09:43
Copy link
Member

@bjlittle bjlittle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rcomer Agreed. We need to consider this a tad more as for me it renders the docs very hard to read

@bjlittle bjlittle merged commit 8d6e659 into SciTools:main Jan 19, 2022
@rcomer rcomer deleted the doc-type-hints branch January 19, 2022 14:22
@pp-mo
Copy link
Member

pp-mo commented Nov 1, 2023

I've been (elsewhere) trialling the option autodoc_typehints = "description"
Not sure if that option post-dates this PR ??
It puts the type-hints into the parameter / returns section, but not the signature, which in practice is much more readable IMHO.


Using this, you can omit the type definitions in the docstring, and sphinx-napoleon will then fill in the parameter/return types from the type hints.
For example ...

def move_one_dimension(content: np.ndarray, from_dim: int, to_dim: int) -> np.ndarray:
    """
    Move one dimension of an array.

    Transpose the input, to shift the selected dimension from one place to another in
    the index order.

    Parameters
    ----------
    content
        an array to be transposed
    from_dim
        the dimension number to 'move'.  ``-1`` means the last
    to_dim
        index of the 'moved' dimension within the output.
        ``0`` means to the first dimension, ``-1`` to the last.

    Returns
    -------
    array
        the result of an appropriate ``content.transpose()`` operation.
    """

Results in ,,,
napoleon_typehinted

I think this is great, as it needs only one DRY statement of types, and it is in a strict vocabulary based on typing, instead of the rather loose numpy docstring format.


It can go wrong though, as when I type the first arg as "np.typing.ArrayLike", this renders as ...
_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

According to the Python command-line, this object prints as
typing.Union[numpy._typing._array_like._SupportsArray[numpy.dtype[typing.Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[typing.Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[typing.Union[bool, int, float, complex, str, bytes]]]

Probably there is a solution to this, but I don't know what as yet.

What I find you can do is revert to putting : :class:'~np.typing.ArrayLike' within the docstring (as well as the type hint) :
That "works", then rendering as content (ArrayLike) – an array to be transposed
-- in that, the 'ArrayLike' is then highlighted but not clickable.

@pp-mo
Copy link
Member

pp-mo commented Nov 3, 2023

More on the above now added here

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

Successfully merging this pull request may close these issues.

3 participants