[英]How can I provide Sphinx documentation for a namedtuple (with autodoc)?
我正在尝试使用 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
生成的文档?
您实际上根本不需要扩展 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
"""
在使用 namedtuple 定义ERBFilterCoeffs
之后,尝试将该文档字符串分配给ERBFilterCoeffs.__doc__
怎么样?
编辑:好的,那么这个怎么样:
class ERBFilterCoeffs(namedtuple('ERBFilterCoeffs','a b c')):
"""
this is the doc string for ERBFilterCoeffs
"""
一般来说,我更喜欢对生成的内容进行更好的控制,而不是向自动模块添加 : automodule
:members:
指令。 因此,我建议使用.. autoclass:: ERBFilterCoeffs
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',
]
)
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.