scanpydoc.elegant_typehints

Format typehints elegantly and and fix automatically created links.

The Sphinx extension sphinx_autodoc_typehints adds type annotations to functions. This extension modifies the created type annotations in four ways:

  1. It formats the annotations more simply and in line with e.g. numpy.

  2. It defines a configuration value qualname_overrides for conf.py that overrides automatically created links. It is used like this:

    qualname_overrides = {
        "pandas.core.frame.DataFrame": "pandas.DataFrame",
        ...,
    }
    

    The defaults include anndata.AnnData, pandas.DataFrame, scipy.sparse.spmatrix and other classes in scipy.sparse.

    It is necessary since __qualname__ does not necessarily match the documented location of the function/class.

    Once either sphinx issue 4826 or sphinx-autodoc-typehints issue 38 are fixed, this part of the functionality will no longer be necessary.

  3. The config value annotate_defaults (default: True) controls if rST code like (default: `42`) is added after the type. It sets sphinx-autodoc-typehints’s option typehints_defaults to 'braces'

  4. Type annotations for tuple return types are added:

    def x() -> Tuple[int, float]:
        """
        Returns:
            a: An integer
            b: A floating point number
        """
    

    will render as:

    Returns
    aint

    An integer

    bfloat

    A floating point number

Functions

example_func(a, b=None)

Example function

Hover over the parameter and return type annotations to see the long versions.

Parameters
a : str | NoneOptional[str]

An example parameter

b : str | int | NoneUnion[str, int, None] (default: None)

Another, with a default

Return type

{str: int}Dict[str, int]

Returns

An example return value

setup(app)

Patches sphinx_autodoc_typehints for a more elegant display.

Parameters
app : Sphinx

Sphinx app to set this extension up for

Return type

{str: Any}Dict[str, Any]

Returns

Metadata for this extension.