Verify code and documentation match

Question

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?

score 0 · Accepted Answer · edited May 23 '17 at 11:45

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]))

Verify code and documentation match

1 Answers1