我应该记录类似功能签名的参数吗？

Question

我有一些辅助函数，除了第一个参数外，其他函数与核心函数的参数相同。这些参数已在核心功能中完整记录。我是否也应该将此文档也复制粘贴到帮助函数中，还是仅指向核心文档？

重要的是，我主要希望将我的API参考阅读为Sphinx生成的HTML，并且我使用numpydoc样式。我在numpydoc manual中找不到答案。

编辑

这里是MWE：

def core(param0, param1=3, param2=8):
    """Core function with thorough documentation.

    Parameters
    ----------
    param0 : ndarray
        Description.
    param1 : int
        Long description.
    param2 : int
        Long description.

    Returns
    -------
    param_out : ndarray
        Long description

    """
    pass

def helper(param3, param1=3, param2=8):
    """Helper function.

    """
    pass

如您所见，两个函数中只有第一个参数不同。

Answer 1

最好，最简单的方法是使用扩展名[[Python Sphinx docstring sections的sphinx.ext.napoleon。

仅

helper函数]特有的参数需要明确记录，您可以remit with a cross-reference定义共享参数的函数/方法。 Google style guide for Python建议重载从基类继承的方法的相同原因：

从基类覆盖方法的方法可能具有简单的文档字符串，将阅读器发送到其重写的方法的文档字符串，例如““”“参见基类。”“”。

基本原理是，无需在很多地方重复基本方法的文档字符串中已经存在的文档。

但是，如果重写方法的行为与重写方法的行为有本质不同，或者需要提供详细信息（例如，记录其他副作用），则在覆盖方法上至少需要具有这些区别的文档字符串。

• Args：

  按名称列出每个参数。名称后应加上描述，并用冒号和空格分隔。

以下示例：

def core(param0, param1=3, param2=8):
    """Core function with thorough documentation.

    Parameters
    ----------
    param0 : ndarray
        Description.
    param1 : int
        Long description.
    param2 : int
        Long description.

    Returns
    -------
    param_out : ndarray
        Long description

    """
    pass

def helper(param3, param1=3, param2=8):
    """Remaining

    Parameters
    ----------
    param3 : int
        Description.
    Other Parameters
        A short string remitting reader to :py:func:`core` function.
    See Also
        A short string remitting reader to :py:func:`core` function.
    Note
        A short string remitting reader to :py:func:`core` function.
    """
    pass

将给出此结果：