pythonparsingpython-sphinxdocstringnumpydoc

How can I parse a numpydoc docstring and access components?


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.


Solution

  • 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.