scanpydoc.elegant_typehints

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",  # fix qualname
    "numpy.int64": ("py:data", "numpy.int64"),  # fix role
    ...,
}

    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#

setup(app)[source]#

Patches sphinx_autodoc_typehints for a more elegant display.

Parameters:
app Sphinx

Sphinx app to set this extension up for

Return type:

dict[str, Any]

Returns:

Metadata for this extension.

Examples#

example_func_anonymous_tuple()[source]#

Example function with anonymous return tuple.

Return type:

tuple[int, str]

Returns:

int

An example int

str

An example str

example_func_prose(a, b=None)[source]#

Example function with a paragraph return section.

Parameters:
a str | None

An example parameter

b str | int | None (default: None)

Another, with a default

Return type:

dict[str, int]

Returns:

An example dict

example_func_tuple()[source]#

Example function with return tuple.

Return type:

tuple[int, str]

Returns:

xint

An example int

ystr

An example str

Contents