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.