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

setup(app)

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_prose(a, b=None)

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()

Example function with return tuple.

Return type:

tuple[int, str]

Returns:

xint

An example int

ystr

An example str

example_func_anonymous_tuple()

Example function with anonymous return tuple.

Return type:

tuple[int, str]

Returns:

int

An example int

str

An example str