Я пытаюсь документировать проект 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?
Как насчет определения ERBFilterCoeffs с помощью namedtuple, попробуйте назначить эту строку doc ERBFilterCoeffs.__doc__?
EDIT: Хорошо, как насчет этого:
class ERBFilterCoeffs(namedtuple('ERBFilterCoeffs','a b c')):
"""
this is the doc string for ERBFilterCoeffs
"""
На самом деле вам не нужно расширять 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
"""
В общем, я предпочитаю иметь более тонкий контроль над тем, что генерируется, чем добавляет директива :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',
]
)