如何解析numpydoc文档字符串和访问组件？

Question

我想解析一个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

我一直在搜索，发现了像农比多和拿破仑这样的东西，但是我还没有找到在我自己的程序中如何使用它们的好线索。我很感谢你的帮助。

Answer 1

您可以使用来自numpydoc的numpydoc将文档字符串解析为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"])

我通过看这个测试在他们的源代码中就知道了这一切。因此，这不是真正的文档，但希望对您来说已经足够开始。