我有一些辅助函数，除了第一个参数之外，它们采用与核心函数相同的参数。这些参数被完整记录在核心函数中。我是否也应该将此文档复制粘贴到辅助函数中，或者只是指向核心文档？
重要的是，我主要希望将我的 API 参考作为 Sphinx 生成的 HTML 来读取，并且我使用 numpydoc 样式。我在 中没有找到答案numpydoc 手册 https://numpydoc.readthedocs.io/en/latest/.
EDIT
这是一个 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
正如您所看到的，两个函数中只有第一个参数不同。
最好、最简单的方法是使用Python Sphinx 文档字符串部分 https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections来自sphinx.ext.napoleon扩大。
仅针对特定的参数辅助函数需要明确记录，您可以交叉引用汇出 https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects定义共享参数的函数/方法。这Python 的 Google 风格指南 https://google.github.io/styleguide/pyguide.html#383-functions-and-methods对于重载从基类继承的方法，建议采用相同的推理：
重写基类方法的方法可能有一个简单的文档字符串，将读者发送到其重写方法的文档字符串，例如“”“参见基类。”“”。理由是不需要在许多地方重复基本方法的文档字符串中已经存在的文档。但是，如果重写方法的行为与被重写方法有很大不同，或者需要提供详细信息（例如，记录其他副作用），则重写方法需要至少具有这些差异的文档字符串。
下面的例子：
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
会给出这样的结果：
本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)
