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

问题描述

我想在一个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文档，但没有找到这个问题的答案，也没有找到演示正确标记的示例。)

---

解决方案

我刚刚构建了一个扩展来完成此任务。到目前为止，它似乎还在使用独立的HTML构建和额外的ReadtheDocs(经过一些调整后)。

该扩展名位于：https://pypi.python.org/pypi/sphinx-paramlinks/。

我现在正在为Alembic和SQLAlChemy项目推出它。(sample)。

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