I'd like to parse a numpydoc docstring and access each component programatically.
For example:
def foobar(a, b):
'''Something something
Parameters
----------
a : int, default: 5
Does something cool
b : str
Wow
'''
What I'd like to do is:
parsed = magic_parser(foobar)
parsed.text # Something something
parsed.a.text # Does something cool
parsed.a.type # int
parsed.a.default # 5
I've been searching around and found things like numpydoc and napoleon but I haven't found any good leads for how to use them in my own program. I'd appreciate any help.
You can use NumpyDocString from numpydoc to parse docstrings into a Python-friendly structure.
This is an example of how to use it:
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"])
However, this won't work with the example you gave (nor a lot of the code I want to run this on) for reasons I don't understand. Instead, you need to use the specific FunctionDoc or ClassDoc class, depending on your use-case.
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"])
I figured this all out by looking at this test in their source code. So, this isn't really documented, but hopefully is enough for you to get started.