以sphinx.autodoc格式解析函数docstring

Question

我在Python的类型中有很多函数:

def foobar(one, two):
    """
    My function.
    :param int one: My one argument.
    :param int two: My two argument.
    :rtype: Something nice.
    """
    return 100 + one + two

我需要解析docstring以获得类似的字典:

{
    'sdesc'  : 'My function.',
    'params' : [('one', 'My one argument.'), ('two', 'My two argument.')],
    'rtype'  : 'Something nice.'
}

我可以使用sphinx.util.docstrings.prepare_docstring如下:

>>> prepare_docstring(foobar.__doc__)
['My function.', ':param int one: My one argument.', ':param int two: My two argument.', ':rtype: Something nice.', '']

我可以创建我自己的解析器,可能使用正则表达式用于params和rtype,以及东西.

但有没有更好的方法来做到这一点或更好的方法？怎么样sphinx.ext.autodoc？关于如何解析这种文档字符串的任何其他建议？

Answer 1

开栈/拉力的parse_docstrings()(永久) 取在新结构化(REST)的函数的文档字符串格式作为输入并返回4个值-SHORT_DESCRIPTION,LONG_DESCRIPTION,则params并返回

例如,如果函数及其docstring是

def sample(self, task, deployment=None):
    """Start benchmark task.

    Implement sample function's long description.

    :param task: Path to the input task file.
    :param deployment: UUID or name of the deployment

    :returns: NIL
    """

然后parse_docstrings()函数将返回 -

{ "short_description" : "Start benchmark task.",
  "long_description" : "Implement sample function's long description.",
  "params": [ { "name" : "task", "doc": "Path to the unput task file" },
              { "name" : "deployment", "doc" :  "UUID or name of the deployment" } ]
  "returns" : "NIL"
}

您可以根据需要修改上述功能.