代码之家 › 专栏 › 技术社区 › Ross Rogers

在Sphinx中,是否有一种在声明参数的同时记录参数的方法?

python-sphinx restructuredtext python

Ross Rogers · 技术社区 · 14 年前

我更喜欢在声明参数的同一行记录每个参数(根据需要),以便应用 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中,通过某种装饰器操作,这可能吗?还有别的办法吗?

3 回复 | 直到 13 年前

ddotsenko 10 年前

我会这么做的。

从这个代码开始。

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

注意代码中多余的逗号;那只是为了让事情保持一致。它没有害处,将来可能会简化事情。

您还可以尝试使用Python编译器获取解析树,修改它并发出更新代码。我为其他语言(不是Python)做过这项工作,所以我对它略知一二,但不知道Python对它的支持有多好。

而且,这是一次性的转换。

Sphinx注释更接近于干注释,因为它们使用的是RST标记语言,这使得它们更易于使用中的普通文本解析工具进行处理 docutils .

只有工具能利用它,它才会干燥。

https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions http://sphinx-doc.org/domains.html#id1

user1496984 11 年前

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

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

Luper Rouch François Lagunas 14 年前

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