Question

我是python-sphinx的新手，无法找到解决以下问题的任何内容：

假设我有一个函数foo(a,b)和bar(a,c)，这样参数a对两个函数都有相同的描述。

是否可以只记录一次a（例如foo中），然后在bar中复制该说明，以避免在{{{}}中更新两段文字1}}的描述发生了变化吗？

例如，说我记录a：

foo

在def foo(a,b,c): """ a function description. :param a: a string, your name :param b: something else """的文档中有什么好处是：

bar

更好，如果它是def bar(a,c) """ another function description. :inheritParams foo a: # somehow inherits a's description from foo :param c: description for parameter c. """和foo(a,b,d)我可以做（在bar(a,c,d)的文档中）：

bar

获取与:inheritParams foo: # grabs a and d documentation from function foo :param c: description for parameter c取得的foo和bar相同的参数说明。也就是说，它会从foo复制a和d的定义，并且我必须记录任何遗留物（foo）。

Answer 1

我不知道你的:inheritParams:想法之类的东西（尽管我喜欢它们！），但你可以使用RestructuredText substitutions来完成主要目标（仅记录一次参数）

基本上，您可以在某处设置替换定义：

.. |param_a_docs| <documentation here>

然后从文档字符串中引用它，如下所示：

def foo(a,b,c):
    """
    a function description.

    :param a: |param_a_docs|
    :param b: something else
    """

设置正确可能有点棘手，因为您需要确保可以找到替换定义，并且将文档字符串放入混合可能会使其变得非常重要。

尝试的一件事是在rst-epilog中设置替换定义。

Answer 2

您可以尝试sphinx-paramlinks。它没有按照您的要求将参数文档从foo复制到bar，但它确实创建了foo中参数文档的超链接。

用python sphinx重复参数

2 个答案: