python sphinx 的重复参数

发布于 2024-12-18 20:01:51 字数 1143 浏览 4 评论 0原文

我是 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)< 就更好了/code> 和 bar(a,c,d) ，我可以做（在 bar 的文档中）：

:inheritParams foo:  # grabs a and d documentation from function foo
:param c: description for parameter c

对与 相同的参数进行任何描述foo 和 bar 取自foo。也就是说，它会从 foo 复制 a 和 d 的定义，并且我必须记录所有剩余内容 (c ）。

原文

I'm new to python-sphinx, and can't find anything addressing the following:

Suppose I have a function foo(a,b) and bar(a,c), such that the parameter a has the same description for both functions.

Is it possible to document a just once (in foo,say) and then copy that description in bar to avoid having to update both pieces of text if something in a's description changes?

For example,
say I document foo:

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

    :param a: a string, your name
    :param b: something else
    """

What would be great is something in bar's documentation like:

def bar(a,c)
    """
    another function description.

    :inheritParams foo a: # somehow inherits a's description from foo
    :param c: description for parameter c.
    """

even better, if it were foo(a,b,d) and bar(a,c,d) and I could do (in bar's documentation):

:inheritParams foo:  # grabs a and d documentation from function foo
:param c: description for parameter c

to have any descriptions of parameters in common with foo and bar taken from foo. That is, it would copy the definition for a and d from foo, and I'd have to document any leftovers (c).

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

伴我心暖 2024-12-25 20:01:51

我不知道像您的 :inheritParams: 想法（尽管我喜欢它们！），但是您可能可以使用 RestructedText 替换

本质上，您可以在类似的地方设置替换定义so：

.. |param_a_docs| <documentation here>

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

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

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

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

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

I don't know of anything like your :inheritParams: ideas (though I like them!), but you could probably accomplish the main goal (only documenting the parameter once) using RestructuredText substitutions

Essentially, you'd set up a substitution definition someplace like so:

.. |param_a_docs| <documentation here>

and then reference it from the docstring like this:

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

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

This might be a little tricky to get set up right, as you need to make sure that the substitution definition can be found, and throwing docstrings into the mix might make that non-trivial.

One thing to try would be to set up the substitution definitions in a rst-epilog.

回复收藏 0 原文