How can I provide Sphinx documentation for a namedtuple (with autodoc)?

Question

I am trying to document a Python project with Sphinx, but I'm having trouble combining the autodoc extension with a namedtuple generated class.

In one document, gammatone.rst, I have:

:mod:`gammatone` -- gammatone filterbank toolkit
================================================

.. automodule:: gammatone
   :members:
.. automodule:: gammatone.coeffs
   :members:

In my gammatone/coeffs.py, I have:

from collections import namedtuple

ERBFilterCoeffs = namedtuple(
    'ERBFilterCoeffs', # Most parameters omitted
    [
        'A0',
        'gain',
    ])

The code generated by namedtuple includes very generic docstrings that Sphinx's autodoc module picks up and includes. I'd rather document the class properly myself, without forgoing autodoc for the rest of the module.

I've tried putting something like this just before the class:

"""
.. class:: ERBFilterCoeffs(A0, gain)
:param A0: A0 coefficient
:param gain: Gain coefficient

Magic coefficients.
"""

...but it doesn't show up in the generated docs. Putting it after the class results in it being nested underneath the generic class documentation, rather than replacing it.

How do I simply tell Sphinx (and the autodoc extension) to use my documentation for the ERBFilterCoeffs class instead of that generated by namedtuple?

Answer 1

How about after defining ERBFilterCoeffs with the namedtuple, try assigning that doc string to ERBFilterCoeffs.__doc__?

EDIT: Ok, how about this then:

class ERBFilterCoeffs(namedtuple('ERBFilterCoeffs','a b c')):
    """
    this is the doc string for ERBFilterCoeffs
    """

Answer 2

You don't actually need to extend the namedtuple at all. You can put the docstring after the namedtuple. This actually works for constants and attributes as well.

ERBFilterCoeffs = namedtuple('ERBFilterCoeffs', ['A0', 'gain', ])
""" Magic coefficients.

.. py:attribute:: A0

    The A0 attribute is something

.. py:attribute:: gain

    The gain attribute is blah blah

"""

Answer 3

In general, I prefer to have finer control over what is generated than adding a :members: directive to automodule gives. As such, I would recommend documenting ERBFilterCoeffs explicitly using .. autoclass:: ERBFilterCoeffs. I would not add a :members: directive here, since that will include the very generic default docs a namedtuple creates for each field. Instead, I would use .. py:attribute:: ... elements in your docstring, which you can put before the class definition using the special #: comments:

#: Magic coefficients.
#:
#: .. py:attirbute:: A0
#:
#:    A0 coefficient
#:
#: .. py:attribute:: gain
#:
#:    Gain coefficient
ERBFilterCoeffs = namedtuple(
    'ERBFilterCoeffs', [# Most parameters omitted
        'A0',
        'gain',
    ]
)