18

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
SethMMorton
  • 45,752
  • 12
  • 65
  • 86
  • 6
    What you have there seems really bad design. Instead you should have a `_foo` function where the `_hidden_parameter` isn't hidden at all, though the documentation warns against the use of the `_foo` function, and then a `foo` with *only* two parameters that simply calls `_foo` with the correct values. When you need the last parameter you use `_foo` and when you don't need it you use `foo` like the end users. – Bakuriu Jun 05 '15 at 07:48
  • 1
    @Bakuriu I completely agree, and in a personal project I would likely take this approach. Unfortunately, this is documentation for someone else's code over which I do not control :/ – SethMMorton Jun 05 '15 at 16:21

3 Answers3

7

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.

ljk321
  • 16,242
  • 7
  • 48
  • 60
7

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

mzjn
  • 48,958
  • 13
  • 128
  • 248
  • This should be the accepted answer, it is spot on and this process works great. I put something like the above into its own .py file and then added the name of that file without the extension to the "extensions" list in the Sphinx conf.py file. – Marc Liyanage May 25 '23 at 22:53
2

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/

Rad Haring
  • 905
  • 7
  • 7