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

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.

I've just built an extension to accomplish this task. So far it seems to be working with standalone HTML build and additionally with readthedocs (after some more tweaks).

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

I'm rolling it out right now for the Alembic and SQLAlchemy projects. (sample).

I take disagreement with the suggestion that linking to params means the docs are too lengthy. The Python standard library is a poor example here as stdlib functions are necessarily granular and simple. Software that is accomplishing a more coarse-grained task, where a single function rides on top of a complex problem to be solved, will often have parameters that require a lot more explanation; this explanation is often quite valuable as the solution to a particular problem elsewhere, and therefore being able to link to it is very important.

For those, that want to use sphinx-paramlinks with sphinx.ext.napoleon here is a patch. Simple find the right fragment in the sphinx-paramlinks source code (sphinx_paramlinks\sphinx_paramlinks.py, somewhere around line 50) and replace it with this:

def cvt(m):
    directive, modifier, objname, paramname = (
        m.group(1), m.group(2) or '', name, m.group(3))
    if directive == 'param':
        refname = _refname_from_paramname(paramname, strip_markup=True)
        item = ('single', '%s (%s parameter)' % (refname, objname),
                '%s.params.%s' % (objname, refname), '')
        if LooseVersion(__version__) >= LooseVersion('1.4.0'):
            item += (None,)
        doc_idx.append(item)
    return ":%s %s_sphinx_paramlinks_%s.%s:" % (
        directive, modifier, objname, paramname)
return re.sub(r'^:(param|type) ([^:]+? )?([^:]+?):', cvt, line)

Note: remember about the right indent.

I'm not a Sphinx specialist, but this seems to get the job done.