是否可以在 Sphinx 中隐藏 Python 函数参数？

Question

假设我在 Numpydoc style, and the documentation is auto-generated with the Sphinx autofunction directive 中记录了以下函数：

def foo(x, y, _hidden_argument=None):
    """
    Foo a bar.

    Parameters
    ----------
    x: str
        The first argument to foo.
    y: str
        The second argument to foo.

    Returns
    -------
    The barred foo.

    """
    if _hidden_argument:
        _end_users_shouldnt_call_this_function(x, y)
    return x + y

我不想将隐藏参数作为我的 public API 的一部分进行宣传，但它显示在我自动生成的文档中。有什么方法可以告诉 Sphinx 忽略函数的特定参数，或者（甚至更好）让它自动忽略带有前导下划线的参数？

Answer 1

我认为 Sphinx 中没有这样的选项。无需破解代码即可实现此目的的一种可能方法是使用自定义签名。

在这种情况下，您需要这样的东西：

.. autofunction:: some_module.foo(x, y)

这将覆盖函数的参数列表并在文档中隐藏不需要的参数。

Answer 2

可以在 autodoc-process-signature 事件的处理程序中编辑函数签名。

事件处理程序的signature参数持有签名； (parameter_1, parameter_2) 形式的字符串。在下面的代码片段中，split() 用于删除函数的最后一个参数：

hidden = "_hidden_argument"

def process_sig(app, what, name, obj, options, signature, return_annotation):
    if signature and hidden in signature:
        signature = signature.split(hidden)[0] + ")" 
    return (signature, return_annotation)

def setup(app):
    app.connect("autodoc-process-signature", process_sig)

结果是文档将问题中函数的签名显示为 foo(x, y) 而不是 foo(x, y, _hidden_argument=None)。

Answer 3

我同意这可能是设计不佳的症状——但我刚刚运行遇到了一个案例，我不得不插入一个无用的 **kwargs 参数来满足 mypy 静态类型检查员...

因此，根据 mzjn 的建议，我发布了一个简单的 sphix 扩展来隐藏文档中的参数：

https://pypi.org/project/sphinxcontrib-autodoc-filterparams/

是否可以在 Sphinx 中隐藏 Python 函数参数？

Is it possible to hide Python function arguments in Sphinx?

python

python-sphinx

numpydoc