如何解析 numpydoc 文档字符串并访问组件？答案

【问题标题】：How can I parse a numpydoc docstring and access components?如何解析 numpydoc 文档字符串并访问组件？
【发布时间】：2016-06-20 18:56:52
【问题描述】：

我想解析一个 numpydoc 文档字符串并以编程方式访问每个组件。

例如：

def foobar(a, b):
   '''Something something

   Parameters
   ----------
   a : int, default: 5
        Does something cool
   b : str
        Wow
'''

我想做的是：

parsed = magic_parser(foobar)
parsed.text  # Something something
parsed.a.text  # Does something cool
parsed.a.type  # int
parsed.a.default  # 5

我一直在四处寻找，发现了 numpydoc 和 napoleon 之类的东西，但我还没有找到任何关于如何在我自己的程序中使用它们的好线索。如有任何帮助，我将不胜感激。

【问题讨论】：

我知道你可以使用inspect 来获取信息，但它不解析文档字符串，只解析注释和默认值，所以def foobar(a=5:"Does something cool", b=DEFAULT : "Wow"): 的签名很容易inspect。
是的，使用inspect 会很好，但是我想解析的文档字符串不是我写的，不幸的是不要使用注释。不过谢谢！
@tal 同意，人们肯定在这样做。我只是还没有找到一个很好的面向客户的库来在我们自己的程序中使用它。

标签： python parsing python-sphinx docstring numpydoc

【解决方案1】：

您可以使用来自numpydoc 的 NumpyDocString 将文档字符串解析为 Python 友好的结构。

这是一个如何使用它的示例：

from numpydoc.docscrape import NumpyDocString


class Photo():
    """
    Array with associated photographic information.


    Parameters
    ----------
    x : type
        Description of parameter `x`.
    y
        Description of parameter `y` (with type not specified)

    Attributes
    ----------
    exposure : float
        Exposure in seconds.

    Methods
    -------
    colorspace(c='rgb')
        Represent the photo in the given colorspace.
    gamma(n=1.0)
        Change the photo's gamma exposure.

    """

    def __init__(x, y):
        print("Snap!")

doc = NumpyDocString(Photo.__doc__)
print(doc["Summary"])
print(doc["Parameters"])
print(doc["Attributes"])
print(doc["Methods"])

但是，由于我不明白的原因，这不适用于您提供的示例（也不适用于我要运行的许多代码）。相反，您需要使用特定的 FunctionDoc 或 ClassDoc 类，具体取决于您的用例。

from numpydoc.docscrape import FunctionDoc

def foobar(a, b):
   """
   Something something

   Parameters
   ----------
   a : int, default: 5
        Does something cool
   b : str
        Wow
   """

doc = FunctionDoc(foobar)
print(doc["Parameters"])

我通过查看this test in their source code 了解了这一切。因此，这并没有真正记录在案，但希望足以让您开始。

【讨论】：