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.
Comments
Post a Comment