Intersphinx Docstring Readability

232 Views Asked by At

Intersphinx is a very nice tool in order to put cross-references into package documentations. However, one issue is that the way these cross-references are written results in reduced legibility of the docstrings when read with help(function) in the terminal or function? in a jupyter-notebook.

Consider the following example:

def time2int(ds: Series) -> Series:
    """Convert :class:`~pandas.Series` encoded as 
    :class:`~numpy.datetime64` or :class:`~numpy.timedelta64` to :class:`int`

    Parameters
    ----------
    ds: Series

    Returns
    -------
    Series
    """

Note that thanks to a type alias, the Parameter and Return Type actually do not require the :class:`~pandas. prefix:

napoleon_type_aliases = {
    "Series" : "~pandas.Series"
}

Is there an easy way to achieve the same for the function description part of the docstring? Ideally, I would hope that there is a way to define a macro that reduces the amount of noise (= non-content characters) in the docstring as much as possible. If it were possible to define macro / cross-reference such that we could write Series_ or :Series: or something similar instead of :class:`~pandas.Series` and get the same formatting would already be a huge improvement.

0

There are 0 best solutions below