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

i'd reference previously-documented function parameter elsewhere in python docstring. consider following (admittedly artificial) example:

def foo(bar):     """perform foo action     :param bar: bar parameter     """      def nested():         """some nested function depends on enclosing scope's bar parameter.         i'd reference function foo's bar parameter here         link, possible?"""         return bar * bar      # ...     return nested() 

is there simple way embed parameter reference using sphinx markup, or happen automagically?

(i'm complete sphinx newbie. i've been scanning sphinx docs , haven't found answer question, or example demonstrating proper markup.)

i've built extension accomplish task. far seems working standalone html build , additionally readthedocs (after more tweaks).

the extension available at: https://pypi.python.org/pypi/sphinx-paramlinks/.

i'm rolling out right alembic , sqlalchemy projects. (sample).

i take disagreement suggestion linking params means docs lengthy. python standard library poor example here stdlib functions granular , simple. software accomplishing more coarse-grained task, single function rides on top of complex problem solved, have parameters require lot more explanation; explanation quite valuable solution particular problem elsewhere, , therefore being able link important.