17

假设我有以下以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 忽略函数的特定参数，或者（甚至更好）使其自动忽略带前导下划线的参数？

4

3 回答 3

7

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

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

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

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

于 2015-06-01T22:44:59.087 回答
6

可以在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).

于 2015-06-03T19:40:45.580 回答
2

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

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

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

于 2019-06-26T14:55:40.523 回答