如何使用Sphinx标记引用记录的Python函数参数？

Question

我想在Python文档字符串的其他地方引用先前记录的函数参数.考虑以下(当然是完全人为的)示例:

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()

是否有一种使用Sphinx标记嵌入参数引用的简单方法,还是会自动发生？

(我是一个完整的Sphinx新手.我一直在扫描Sphinx文档,但没有找到这个问题的答案,或者是一个展示正确标记的例子.)

Answer 1

没有简单的方法来直接引用函数的参数,sphinx我不知道这个问题的扩展.

python域的文档说明了哪些对象可以交叉引用.

给用户提供bar函数参数的foo可能方法是

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

也许通过编写扩展名可以直接引用.

Answer 2

我刚刚建立了一个扩展来完成这个任务.到目前为止,它似乎使用独立的HTML构建和readthedocs(经过一些更多的调整).

该扩展程序位于:https://pypi.python.org/pypi/sphinx-paramlinks/.

我正在为Alembic和SQLAlchemy项目推出它.(样本).

我不同意这样的建议,即链接到params意味着文档过于冗长.Python标准库在这里是一个很糟糕的例子,因为stdlib函数必然是粒度和简单的.正在完成更粗粒度任务的软件,其中单个函数位于要解决的复杂问题之上,通常会有需要更多解释的参数; 这种解释通常非常有价值,因为其他地方的特定问题的解决方案,因此能够链接到它是非常重要的.