45

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

4

5 回答 5

35

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.

于 2012-06-24T15:33:27.503 回答
27

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

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

我现在正在为 Alembic 和 SQLAlchemy 项目推出它。（样本）。

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

于 2013-12-30T18:30:39.207 回答
2

对于那些想要在这里使用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)

注意：记住正确的缩进。

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

于 2018-06-05T14:47:45.527 回答
0

并不是说sphinx-paramlinks不是一个很好的解决方案，但我对于为我的项目添加更多扩展有点固执。

您不会获得视觉突出显示或锚图标的好处，这是一个无赖，但该部分之前的 reStructuredText超链接目标至少可以让您关闭：

    def from_existing_id(cls, jobid, **kwargs):
        """Instantiates a new :class:`Job` object from an existing job ID.

        :param jobid: the ID of the previous job
        :param kwargs: keyword arguments supported by :meth:`deserialize`,
            *e.g.*, :ref:`ignore_missing <deserialize_params>`.
        """
        ⋮

    # elsewhere
    def deserialize(self, filename, copy_inputs=False, ignore_missing=False):
        """Reads a disk file into the current :class:`Job` object's config.
    
        .. _deserialize_params:

        :param filename: the filename to read from to disk
        :param copy_inputs: copy input files to output directory
        :param ignore_missing: don't bail if input files are missing
        """
        ⋮

但是，您的参数列表越长，它的用处就越小。

于 2022-02-09T11:49:49.323 回答
-1

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

以defaultdict 示例为例：

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 没有超出当前部分范围，因此将稍后的引用呈现为样式文本而不是锚点。如果这是故意的，我不会感到惊讶。

于 2012-06-23T10:08:50.660 回答