Improve docstring return output with typing in sphinx

[paddyroddy]

In addition, just now I experimented a bit with https://github.com/tox-dev/sphinx-autodoc-typehints and this could provide the kind of annotation we would like to see:

def vmap_galactic_ecliptic(
    nside: int,
    galactic: tuple[float, float] = (30, 90),
    ecliptic: tuple[float, float] = (20, 80),
) -> npt.NDArray[typing.Any]:
    """
    ...

    Returns
    -------
    A HEALPix :term:`visibility map`.

    """

Which produces:

Originally posted by @ntessore in #373 (comment)

[ntessore]

I'm happy to experiment with this

[paddyroddy]

@ntessore I'm looking at this as part of #188, have got something like:

# -- autodoc -----------------------------------------------------------------

autodoc_typehints = "description"


# -- napoleon ----------------------------------------------------------------

napoleon_google_docstring = False
napoleon_use_rtype = False


# -- sphinx-autodoc-typehints ----------------------------------------------------------------

always_use_bars_union = True
typehints_use_rtype = False
typehints_defaults = "comma"

with these settings, but I can't work out how to get rid of the redundant Returns... Any idea?

[ntessore]

To be honest, I am starting to think perhaps having separate "returns" and "return type" sections is a feature, not a bug. For simple return types, this isn't the worst output:

Returns:
  The value of the thing.

Return type:
  int

Whereas for complicated situations, having both sections allows for much more nuance:

Returns:
  - a (int) -- The value of a. Only returned if return_a is true.    <  These are manually
  - b (float) -- The value of b. Only returned if return_b is true.  <  written out in the
  - c (bool) -- The value of c. Only returned if return_c is true.   <  "returns" section.

Return type:
  <some complicated mess that is impossible to understand, ideally suppressed>

[ntessore]

Perhaps a good question to answer first is whether the documentation of from_convergence() can be made human-readable using a number of @typing.overload?

[paddyroddy]

Discussed in a call. Going to keep Returns and Return type. Can be addressed again in the future if we want.