Is it possible to hide Python function arguments in Sphinx?

Question

Suppose I have the following function that is documented in the 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

I don't want to advertise the hidden argument as part of my public API, but it shows up in my auto-generated documentation. Is there any way to tell Sphinx to ignore a specific argument to a function, or (even better) make it auto-ignore arguments with a leading underscore?

Answer 1

I don't think there is an option for that in Sphinx. One possible way to accomplish this without having to hack into the code, is to use customized signature.

In this case, you need something like:

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

This will override the parameter list of the function and hide the unwanted argument in the doc.

Answer 2

It is possible to edit the function signature in a handler for the autodoc-process-signature event.

The signature parameter of the event handler holds the signature; a string of the form (parameter_1, parameter_2). In the snippet below, split() is used to remove the last parameter of a function:

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)

The result is that the documentation will show the signature of the function in the question as foo(x, y) instead of foo(x, y, _hidden_argument=None).

Answer 3

I agree that it's probably a symptom of poor design -- but I've just run into a case where I had to insert a useless **kwargs argument just to satisfy the mypy static type checker...

So, building on the suggestion by mzjn, I've published a simple sphix extension to hide arguments from the documentation:

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