pythonpython-sphinxnumpydoc

Verify code and documentation match


Using Sphinx extension NumpyDoc, is there some way to automatically make sure that the documentation matches the code it's documenting?

For example, the following documentation does not match the code due to a typo:

def myfunc(apples, bears):
"""
    Parameters
    ----------
    apples : int
        The number of apples.
    beards : int
        The number of bears to eat the apples.
"""

Can Sphinx or NumpyDoc make this an error?


Solution

  • This is built into NumpyDoc or Sphinx, but it is possible using NumpyDoc's scraping abilities. Here is a code snippet that accomplishes the desired functionality:

    import inspect
    
    from numpydoc.docscrape import FunctionDoc
    
    def myfunc(apples, bears):
        """
            Parameters
            ----------
            apples : int
                The number of apples.
            beards : int
                The number of bears to eat the apples.
        """
    
    doc = FunctionDoc(myfunc)
    argspec = inspect.getargspec(myfunc)
    
    # check for basic spelling errors
    for a_i, arg in enumerate(argspec.args):
        if arg != doc["Parameters"][a_i][0]:
            print("%s != %s" %(arg, doc["Parameters"][a_i][0]))