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?

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
– Bakuriu, Commented Jun 5, 2015 at 7:48
@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
– SethMMorton, Commented Jun 5, 2015 at 16:21

mzjn · Accepted Answer · 2020-05-09 07:23:39Z

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

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.

ljk321 · Accepted Answer · 2015-06-07 03:24:28Z

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.

Collectives™ on Stack Overflow

Is it possible to hide Python function arguments in Sphinx?

2 Answers 2

1 Comment

Comments

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

Comments

Linked

Related