Menu
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.
829
Docstrings are accessible from the doc attribute (__doc__) for any of the Python objects and also with the built-in help() function. An object's docstring is defined by including a string constant as the first statement in the object's definition.
Declaring Docstrings: The docstrings are declared using ”'triple single quotes”' or “””triple double quotes””” just below the class, method or function declaration. All functions should have a docstring.
A Python docstring is a string used to document a Python module, class, function or method, so programmers can understand what it does without having to read the details of the implementation. Also, it is a common practice to generate online (html) documentation automatically from docstrings.
A documentation string (docstring) is a string that describes a module, function, class, or method definition. The docstring is a special attribute of the object ( object. __doc__ ) and, for consistency, is surrounded by triple double quotes, i.e.: """This is the form of a docstring.
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.
148
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
