python - 我应该记录类似函数签名的参数吗？

Question

我有一些辅助函数，除了第一个参数外，它们采用与核心函数相同的参数。这些参数在核心函数中得到了详尽的记录。我是否也应该将此文档复制粘贴到辅助函数中，还是只指向核心文档？

重要的是，我主要打算将我的 API 引用读取为 Sphinx 生成的 HTML，并且我使用 numpydoc 样式。我在numpydoc 手册中没有找到答案。

编辑

这是一个 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 文档字符串部分sphinx.ext.napoleon。

只有辅助函数独有的参数需要明确记录，您可以通过对定义共享参数的函数/方法的交叉引用进行汇款。Python的Google 风格指南建议重载从基类继承的方法的相同推理：

重写基类中的方法的方法可能有一个简单的文档字符串，将阅读器发送到其重写方法的文档字符串，例如“”“参见基类。”“”。基本原理是不需要在许多地方重复基本方法的文档字符串中已经存在的文档。但是，如果重写方法的行为与重写方法有很大不同，或者需要提供详细信息（例如，记录额外的副作用），则重写方法需要至少具有这些差异的文档字符串。

• 参数：

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

下面的例子：

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

会给出这个结果：