1

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.

mzjn
  • 48,958
  • 13
  • 128
  • 248
Hyperplane
  • 1,422
  • 1
  • 14
  • 28
  • You could remove it from the docstring and put it in narrative documentation. Otherwise, I don't know of any option that does what you want. – Steve Piercy Jun 16 '21 at 06:04
  • 1
    Similar feature request: https://github.com/sphinx-doc/sphinx/issues/5456 – mzjn Jun 16 '21 at 06:36

0 Answers0