Intersphinx 文档字符串可读性

编程问答 2022-04-24

问题描述

Intersphinx 是一个非常好的工具，用于将交叉引用放入包文档中。然而，一个问题是，当在终端中使用 help(function) 或在 jupyter-notebook 中使用 function? 阅读时，这些交叉引用的写入方式会降低文档字符串的易读性。

考虑以下示例：

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
    """

请注意，由于类型别名，参数和返回类型实际上不需要 :class:`~pandas. 前缀：

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

对于文档字符串的函数描述部分，是否有一种简单的方法可以实现相同的目标？理想情况下，我希望有一种方法可以定义一个宏，以尽可能减少文档字符串中的噪音（= 非内容字符）。如果可以定义宏/交叉引用，以便我们可以编写 Series_ 或 :Series: 或类似的东西而不是 :class:`~pandas.Series` 并获得相同的格式，那将是一个巨大的改进。

解决方法

暂无找到可以解决该程序问题的有效方法，小编努力寻找整理中！

如果你已经找到好的解决方法，欢迎将解决方案带上本链接一起发送给小编。

小编邮箱:dio#foxmail.com (将#修改为@）

docstringpythonpython-sphinxsphinx-napoleon