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函数的参数，我不知道这个问题的扩展名。

documentation of the python domain解释了哪些对象可以交叉引用。

为用户提供对函数bar的参数foo的引用的可能方法是

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

也许通过撰写扩展名可以直接引用。

Answer 2

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

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

我正在为Alembic和SQLAlchemy项目推出它。（sample）。

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

Answer 3

对于那些想要在sphinx-paramlinks使用sphinx.ext.napoleon的人来说，这是一个补丁。在sphinx-paramlinks源代码（sphinx_paramlinks \ sphinx_paramlinks.py，第50行左右）中找到正确的片段并将其替换为：

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)

注意：记住右缩进。

我不是狮身人面像专家，但这似乎完成了工作。

Answer 4

如果您正在寻找直接链接到bar foo定义的方法，那么您的文档太长了或者您要求您的读者忽略一棵树或某种组合的森林两个。

以defaultdict Examples：

为例

Setting the :attr:`default_factory` to :class:`int` makes the
:class:`defaultdict` useful for counting (like a bag or multiset in other
languages):

如果我不能费心阅读collections.defaultdict中的五个句子以找到default_factory的含义，我可能不应该在那里领导。

请注意，属性引用语法与上一节中的相同：

The first argument provides the initial value for the :attr:`default_factory`
attribute; it defaults to ``None``.

但看起来Sphinx没有达到当前部分范围之外，因此将后面的引用呈现为样式文本而不是锚点。如果这是故意的话，我不会感到惊讶。

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

4 个答案: