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

Question

假设我有一个记录在Numpydoc style中的函数，并且文档是用Sphinxautofunction 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

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

Answer 1

我不认为在斯芬克斯有这样的选择。一种不必侵入代码就能实现这一点的可能方法是使用自定义签名。在

在这种情况下，您需要类似于：

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

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

Answer 2

我同意这可能是设计不好的症状，但是我遇到了这样的情况：我不得不插入一个无用的**kwargs参数来满足mypy静态类型检查器的要求。。。在

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

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

Answer 3

可以在^{}事件的处理程序中编辑函数签名。在

事件处理程序的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)。在