Removing namedtuple docstrings for Sphinx

namedtuples are awesome. Unfortunately, if you find yourself with a large one, and you use Sphinx for documentation, you're going to find yourself with a gigantic part of your documentation looking like this:

See those "Alias for field number" comments? In most cases, this information is pretty much useless since the information is already in the class signature anyway, and it just clutters the documentation (in this case it's not actually in the class signature, but this namedtuple doesn't make sense to be used in a tuple-like fashion, so it's useless anyway).

I went out to find some option for autoclass that would allow me to disable the docstrings for particular members, but I didn't find anything.

I eventually found autodoc-process-docstring, a Sphinx event that you can attach a handler to. Essentially, it hands you the list of lines that comprise the docstring, and you modify the list in place. Sphinx will then use whatever the list looks like after the function has ran as the docstring.

In our case, we want to remove all attributes that just document that they are an alias for a field number. Doing so is as simple as adding this function to conf.py:

def no_namedtuple_attrib_docstring(app, what, name,
                                   obj, options, lines):
    is_namedtuple_docstring = (
        len(lines) == 1 and
        lines[0].startswith('Alias for field number')
    )
    if is_namedtuple_docstring:
        # We don't return, so we need to purge in-place
        del lines[:]

Now, we need to tell Sphinx to run this function as part of its docstring processing. To do so, we attach this function as a callback to the event autodoc-process-docstring:

def setup(app):
    app.connect(
        'autodoc-process-docstring',
        no_namedtuple_attrib_docstring,
    )

Now, the documentation looks like this: