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

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

编辑：好的，那么：

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

Answer 3

一般来说，我更倾向于对:members:指令添加automodule指令进行更精细的控制。因此，我建议明确使用ERBFilterCoeffs记录.. autoclass:: ERBFilterCoeffs。我不会在这里添加:members:指令，因为它将包含namedtuple为每个字段创建的非常通用的默认文档。相反，我会在你的docstring中使用.. py:attribute:: ...个元素，你可以使用特殊的#:注释将它们放在类定义之前：

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

如何为namedtuple（使用autodoc）提供Sphinx文档？

3 个答案: