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

Question

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

pythonparameterspython-sphinxsphinx-napoleon

3

我有一些辅助函数，除了第一个参数外，其余参数与核心函数相同。这些参数在核心函数中得到了详细的文档说明。我应该将这些文档复制粘贴到辅助函数中，还是只需指向核心文档即可？

如果有所影响，我主要打算将我的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

正如您所看到的，这两个函数中只有第一个参数不同。

- Zoltán Csáti

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- bad_coder · Accepted Answer

最好、也是最简单的方法是使用sphinx.ext.napoleon扩展中的Python Sphinx文档字符串部分。

只需明确记录与助手函数相关的参数，您就可以使用交叉引用remits到定义共享参数的函数/方法。Python的Google风格指南建议在从基类重载继承方法时采用相同的理由：

一个覆盖基类方法的方法可能有一个简单的文档字符串，将读者引导到其被覆盖方法的文档字符串，例如"""See base class.""". 其理由是没有必要在许多地方重复文档，因为这些文档已经在基本方法的文档字符串中出现。 然而，如果覆盖方法的行为与被覆盖方法显著不同，或需要提供细节（例如记录其他副作用），则需要在覆盖方法上至少使用这些差异的文档字符串。

参数：

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

以下是一个示例：

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

会得到这个结果：