如何为namedtuple(使用autodoc)提供Sphinx文档？

Question

我试图用Sphinx记录一个Python项目,但是我在将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？

Answer 1

实际上你根本不需要扩展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

"""

Answer 2

在ERBFilterCoeffs使用namedtuple 定义后,尝试将该文档字符串分配给ERBFilterCoeffs.__doc__？

编辑:好的,那么这个怎么样:

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