在Sphinx中，有没有一种在声明参数的同时记录参数的方法？ [英] In Sphinx, is there a way to document parameters along with declaring them?

问题描述

为了应用D.R.Y.

，我更喜欢在声明参数的同一行上记录每个参数(根据需要)

如果我有如下代码：

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.]

在带有某种修饰符操作的python2.6或python3中，这是可能的吗？还有别的办法吗？

推荐答案

我会这么做。

从此代码开始。

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
   """
    ...

这是用来填充文档模板的各种参数字符串模式的一些非常简单的正则表达式处理。

很多优秀的PythonIDE(例如，PyCharm)都理解默认的Sphinxparam表示法，甚至在IDE认为不符合声明类型的作用域中标记变量/方法。

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

您还可以尝试并使用Python编译器来获取解析树、修改它并发出更新代码。我曾经在其他语言(不是Python)上这样做过，所以我对它略知一二，但不知道在Python中对它的支持有多好。

此外，这是一次性转换。

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

Sphinx注释更接近于干，因为它们是RST标记语言，因此在docutils中使用普通文本分析工具处理它们要容易得多。

只有工具可以使用它，它才是干的。

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

这篇关于在Sphinx中，有没有一种在声明参数的同时记录参数的方法？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！