12

我正在尝试用 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包含 Sphinxautodoc模块提取并包含的非常通用的文档字符串。我宁愿自己正确地记录课程，而不放弃autodoc模块的其余部分。

我试过在上课前放这样的东西：

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

Magic coefficients.
"""

...但它没有出现在生成的文档中。将它放在类之后会导致它嵌套在通用类文档下面，而不是替换它。

我如何简单地告诉 Sphinx（和autodoc扩展）使用我的ERBFilterCoeffs类文档而不是生成的类namedtuple？

4

3 回答 3

13

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

"""
于 2013-12-13T18:23:17.460 回答
7

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

编辑：好的，那么这个怎么样：

class ERBFilterCoeffs(namedtuple('ERBFilterCoeffs','a b c')):
    """
    this is the doc string for ERBFilterCoeffs
    """
于 2012-12-09T06:14:45.710 回答
-1

一般来说，我更喜欢对生成的内容进行更好的控制，而不是在给定中添加:members:指令automodule。因此，我建议ERBFilterCoeffs使用.. autoclass:: ERBFilterCoeffs. 我不会在这里添加指令，因为这将包括为每个字段创建:members:的非常通用的默认文档。namedtuple相反，我会在您的文档字符串中使用.. py:attribute:: ... 元素，您可以使用特殊#:注释将其放在类定义之前：

#: Magic coefficients.
#:
#: .. py:attirbute:: A0
#:
#:    A0 coefficient
#:
#: .. py:attribute:: gain
#:
#:    Gain coefficient
ERBFilterCoeffs = namedtuple(
    'ERBFilterCoeffs', [# Most parameters omitted
        'A0',
        'gain',
    ]
)
于 2017-12-22T21:31:44.640 回答