用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:想法（虽然我喜欢它们！），但你可能可以使用 RestructedText替换来实现主要目标（仅记录参数一次）

本质上，您可以像这样在某个地方设置替换定义：

.. |param_a_docs| <documentation here>

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

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

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

正确设置可能有点棘手，因为您需要确保可以找到替换定义，并且将文档字符串放入混合中可能会使这变得不那么简单。

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