python - 解析 Sphinx 之类的文档

Question

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

Answer 1

您可以使用docutils，这是 Sphinx 的基础。在另一个答案中，我使用docutils.core.publish_doctree获取 reStructuredText 文档（实际上是文本字符串）的 XML 表示，然后使用 xml.minidom 方法从该 XML 中提取字段列表。另一种方法是使用 xml.etree.ElementTree，在我看来它更容易使用。

然而，首先，每次 docutils 遇到 reStructuredText 块时

: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并将文本作为 2 元组放入列表中。然后，您可以按照您希望的方式进行后期处理。field/field_namefield/field_body/paragraph

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 来获得他们想要的确切输出。