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

Question

假设我具有Numpydoc样式中记录的以下函数,并且使用Sphinx autofunction指令自动生成文档:

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

我不想将隐藏的参数作为我公共API的一部分进行宣传,但它会显示在我自动生成的文档中.有没有办法告诉Sphinx忽略一个函数的特定参数,或者(甚至更好)让它自动忽略带有前导下划线的参数？

Answer 1

我不认为在Sphinx中有这样的选择.在不必破解代码的情况下实现此目的的一种可能方法是使用自定义签名.

在这种情况下,您需要以下内容:

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

这将覆盖函数的参数列表并隐藏doc中不需要的参数.

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)。