Как я могу предоставить документацию Sphinx для namedtuple (с помощью autodoc)?

Я пытаюсь документировать проект Python с помощью Sphinx, но у меня возникают проблемы с объединением расширения autodoc с классом namedtuple.

В одном документе gammatone.rst у меня есть:

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

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

В моем gammatone/coeffs.py у меня есть:

from collections import namedtuple

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

Код, сгенерированный namedtuple, включает в себя очень общие докстры, которые модуль Sphinx autodoc берет и включает. Я предпочел бы правильно документировать класс, не оставляя autodoc для остальной части модуля.

Я попытался поставить что-то вроде этого непосредственно перед классом:

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

Magic coefficients.
"""

... но он не отображается в сгенерированных документах. Положив его после класса, он будет вложен под документами общего класса, а не заменяет его.

Как просто сказать Sphinx (и расширение autodoc) использовать мою документацию для класса ERBFilterCoeffs вместо сгенерированного namedtuple?

Ответ 1

Как насчет определения ERBFilterCoeffs с помощью namedtuple, попробуйте назначить эту строку doc ERBFilterCoeffs.__doc__?

EDIT: Хорошо, как насчет этого:

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

Ответ 2

На самом деле вам не нужно расширять namedtuple. Вы можете поставить docstring после namedtuple. Это действительно работает и для констант и атрибутов.

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

.. py:attribute:: A0

    The A0 attribute is something

.. py:attribute:: gain

    The gain attribute is blah blah

"""

Ответ 3

В общем, я предпочитаю иметь более тонкий контроль над тем, что генерируется, чем добавляет директива :members: к automodule. Поэтому я бы рекомендовал документировать ERBFilterCoeffs явно используя .. autoclass:: ERBFilterCoeffs. Я бы не добавил директиву :members: здесь, так как это будет включать в себя очень общие документы по умолчанию, которые создает namedtuple для каждого поля. Вместо этого я использовал бы элементы .. py:attribute:: ... в вашей docstring, которые вы можете поставить перед определением класса, используя специальные комментарии #::

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