在 Sphinx 中，有没有办法在声明参数的同时记录参数？

Question

我更喜欢在声明参数的同一行记录每个参数（根据需要），以便应用 DRY

如果我有这样的代码：

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
   ):
    ...

如何避免重复文档字符串中的参数并保留参数解释？

我想避免：

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
    ):
    '''Foo does whatever.

    * flab_nickers - a series of under garments to process
    * needs_pressing - Whether the list of garments should all be pressed.
      [Default False.]

在 python 2.6 或 python 3 中通过某种装饰器操作可能实现这一点吗？还有其他办法吗？

Answer 1

我会这样做。

从这段代码开始。

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
   ):
    ...

我会编写一个解析器来获取函数参数定义并构建以下内容：

def foo(
        flab_nickers, 
        has_polka_dots=False,
        needs_pressing=False,
   ):
   """foo

   :param flab_nickers: a series of under garments to process
   :type flab_nickers: list or tuple
   :param has_polka_dots: default False
   :type has_polka_dots: bool
   :param needs_pressing: default False, Whether the list of garments should all be pressed
   :type needs_pressing: bool
   """
    ...

这是对各种参数字符串模式进行一些相当直接的正则表达式处理，以填充文档模板。

许多优秀的 Python IDE（例如 PyCharm）都理解默认的 Sphinx param 表示法，甚至在 IDE 认为不符合声明类型的范围内标记变量/方法。

注意代码中多余的逗号；这只是为了让事情保持一致。它没有坏处，而且可能会简化将来的事情。

您还可以尝试使用 Python 编译器获取解析树，对其进行修改并发出更新代码。我已经为其他语言（不是Python）做过这个，所以我对它有一点了解，但不知道它在Python中的支持程度如何。

而且，这是一次性转变。

函数定义中的原始内联注释并不真正遵循 DRY，因为它是一种非正式语言的注释，除了最复杂的工具之外，任何其他工具都无法使用它。

Sphinx 注释更接近 DRY，因为它们采用 RST 标记语言，这使得使用 docutils 中的普通文本解析工具更容易处理它们。

只有工具可以利用它，它才是 DRY。

有用的链接：
https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions
http://sphinx-doc.org/domains.html#id1

Answer 2

注释旨在部分解决 Python 3 中的此问题：

http://www.python。 org/dev/peps/pep-3107/

我不确定是否有任何工作将这些应用到 Sphinx 上。

Answer 3

如果没有预处理器，您就无法做到这一点，因为一旦编译了源代码，Python 就不存在注释了。为了避免重复，请删除注释并仅在文档字符串中记录参数，这是记录参数的标准方法。