以 sphinx.autodoc 格式解析函数文档字符串

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

而且我需要解析文档字符串以获得类似于以下内容的字典：

{
    '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.', '']

我可以创建自己的解析器，也许对参数和 rtype 使用正则表达式等等。

但是有没有更好的方法或更好的方法呢？ sphinx.ext.autodoc 是怎么做到的？有关如何解析此类文档字符串的任何其他建议？

Answer 1

openstack/rally的parse_docstrings() (permalink) 以 reStructuredText (reST) 格式的函数文档字符串作为输入并返回 4 个值 -short_description、long_description、params 和返回

例如如果函数及其文档字符串是

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

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

Answer 2

编辑：

这个问题两年没有回复。查看接受的回复以获得更好的选择。

---

旧：

我最终使用了正则表达式。 Sphinx 使用的嵌套 Nodes 的特定系统，其中每个节点类型都必须解析它们的子节点，这对我的目的不是很有用。如果有人关心，这是我使用的正则表达式：

param_regex = re.compile(
    '^:param (?P<type>\w+)? (?P<param>\w+): (?P<doc>.*)$'
)

Answer 3

pip install docstring-parser

同时支持 ReST 样式和 Google 样式的文档字符串，

详情请见https://github.com/rr-/docstring_parser