How do I reference a documented Python function parameter using Sphinx markup?

Question

I'd like to reference a previously-documented function parameter elsewhere in a Python docstring. Consider the following (admittedly completely artificial) example:

def foo(bar):
    """Perform foo action
    :param bar: The bar parameter
    """

    def nested():
        """Some nested function that depends on enclosing scope's bar parameter.
        I'd like to reference function foo's bar parameter here
        with a link, is that possible?"""
        return bar * bar

    # ...
    return nested()

Is there a simple way to embed a parameter reference using Sphinx markup, or will this happen automagically?

(I'm a complete Sphinx newbie. I've been scanning the Sphinx docs and haven't found an answer to this question, or an example demonstrating proper markup.)

Answer 1

There is no simple way to get a direct reference to a parameter of a function with sphinx and I don't know an extension for this problem.

The documentation of the python domain explains which objects can be cross referenced.

A possible way to give the user a reference to parameter bar of function foo would be

See parameter ``bar`` in :func:`foo`.

Maybe a direct reference would be possible by writing an extension.