parameters - 使用python sphinx重复参数

Question

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

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

是否可以记录 a只需一次(在 foo 中，比如说)然后在 bar 中复制该描述避免在 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 ，我必须记录任何剩菜( c )。

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 中设置替换定义。 .