python - 像文档一样解析 Sphinx

Question

我有一个 Sphinx 格式的文档字符串，我想从中提取不同的部分(参数、返回、类型、rtype 等)以进行进一步处理。我怎样才能做到这一点？

Answer 1

你可以使用 docutils ，这就是 Sphinx 的基础。在 this other answer我使用 docutils.core.publish_doctree 获取 reStructuredText 文档(实际上是文本字符串)的 XML 表示形式，然后使用 xml.minidom 方法从该 XML 中提取字段列表。另一种方法是使用 xml.etree.ElementTree，我认为它更容易使用。

然而，首先，每次 docutils 遇到像

这样的 reStructuredText block 时

:param x: Some parameter

生成的 XML 表示是(我知道，它非常冗长):

<field_list>
    <field>
        <field_name>
            param x
        </field_name>
        <field_body>
            <paragraph>
                Some parameter
            </paragraph>
        </field_body>
    </field>
</field_list>

以下代码将获取文档中的所有 field_list 元素，并将来自 field/field_name 和 field/field_body/paragraph 的文本作为列表中的 2 元组。然后，您可以按照您希望的方式操作它以进行后期处理。

from docutils.core import publish_doctree
import xml.etree.ElementTree as etree

source = """Some help text

:param x: some parameter
:type x: and it's type

:return: Some text
:rtype: Return type

Some trailing text. I have no idea if the above is valid Sphinx
documentation!
"""

doctree = publish_doctree(source).asdom()

# Convert to etree.ElementTree since this is easier to work with than
# xml.minidom
doctree = etree.fromstring(doctree.toxml())

# Get all field lists in the document.
field_lists = doctree.findall('field_list')

fields = [f for field_list in field_lists \
    for f in field_list.findall('field')]

field_names = [name.text for field in fields \
    for name in field.findall('field_name')]

field_text = [etree.tostring(element) for field in fields \
    for element in field.findall('field_body')]

print zip(field_names, field_text)

这会产生列表:

[('param x', '<field_body><paragraph>some parameter</paragraph></field_body>'),
 ('type x', "<field_body><paragraph>and it's type</paragraph></field_body>"), 
 ('return', '<field_body><paragraph>Some text</paragraph></field_body>'), 
 ('rtype', '<field_body><paragraph>Return type</paragraph></field_body>')]

因此每个元组中的第一项是字段列表项(即 :return:、:param x: 等)，第二项是相应的文本。显然，这段文本不是最干净的输出 - 但上面的代码很容易修改，所以我将其留给 OP 来获得他们想要的确切输出。