如何为命名元组（使用 autodoc）提供 Sphinx 文档？答案

【问题标题】：How can I provide Sphinx documentation for a namedtuple (with autodoc)?如何为命名元组（使用 autodoc）提供 Sphinx 文档？
【发布时间】：2012-12-09 06:08:53
【问题描述】：

我正在尝试使用 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 生成的文档？

【问题讨论】：

标签： python python-sphinx autodoc

【解决方案1】：

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

"""

【讨论】：

在我的例子中，“把它放在类之后会导致它嵌套在通用类文档下面，而不是替换它。”
这行不通。在这里，您创建一个分配给变量 ERBFilterCoeffs 的命名元组，然后在真空中定义一个多行字符串。
@aconrad 这是 sphinx 记录常量的方式，它适用于 sphinx，但可能不适用于 ERBFilterCoeffs.__doc__
您可以在 autoclass 指令中省略 :members:。唯一的问题是在这种情况下你不能依赖:members: 到automodule，你必须手动列出模块内容。
我试过这个方法，它几乎对我有用，但它在属性名称前加上模块名称。我不能使用全局设置add_module_names = False，因为我想在别处使用它们。而且我似乎无法用波浪号 ~ 或类似符号注释 :py:attribute:: some_name 中的 some_name：注释只是按字面意思包含。有没有办法解决这个问题？

【解决方案2】：

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

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

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

【讨论】：

我得到：WARNING: autodoc can't import/find module 'gammatone.erb', it reported error: "attribute '__doc__' of 'type' objects is not writable", please check your spelling and sys.path — 所以大概我无法覆盖namedtuple 生成类型的文档字符串：/
作为副作用，这将显示为base，这有点自相矛盾......除此之外，文档结果很好:)

【解决方案3】：

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

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

【讨论】：