repeated parameters with python sphinx

Question

I'm new to python-sphinx, and can't find anything addressing the following:

Suppose I have a function foo(a,b) and bar(a,c), such that the parameter a has the same description for both functions.

Is it possible to document a just once (in foo,say) and then copy that description in bar to avoid having to update both pieces of text if something in a's description changes?

For example, say I document foo:

def foo(a,b,c):
    """
    a function description.

    :param a: a string, your name
    :param b: something else
    """

What would be great is something in bar's documentation like:

def bar(a,c)
    """
    another function description.

    :inheritParams foo a: # somehow inherits a's description from foo
    :param c: description for parameter c.
    """

even better, if it were foo(a,b,d) and bar(a,c,d) and I could do (in bar's documentation):

:inheritParams foo:  # grabs a and d documentation from function foo
:param c: description for parameter c

to have any descriptions of parameters in common with foo and bar taken from foo. That is, it would copy the definition for a and d from foo, and I'd have to document any leftovers (c).

Answer 1

I don't know of anything like your :inheritParams: ideas (though I like them!), but you could probably accomplish the main goal (only documenting the parameter once) using RestructuredText substitutions

Essentially, you'd set up a substitution definition someplace like so:

.. |param_a_docs| <documentation here>

and then reference it from the docstring like this:

def foo(a,b,c):
    """
    a function description.

    :param a: |param_a_docs|
    :param b: something else
    """

This might be a little tricky to get set up right, as you need to make sure that the substitution definition can be found, and throwing docstrings into the mix might make that non-trivial.

One thing to try would be to set up the substitution definitions in a rst-epilog.

Answer 2

You might try sphinx-paramlinks. It doesn't copy the parameter documentation from foo into bar, as you asked for, but it does create a hyperlink to the parameter documentation in foo.