我试图用Sphinx编写一个Python项目,但是在将autodoc
扩展与namedtuple
生成的类结合起来时遇到了困难。在
在一份文件中,gammatone.rst
,我有:
:mod:`gammatone` -- gammatone filterbank toolkit
================================================
.. automodule:: gammatone
:members:
.. automodule:: gammatone.coeffs
:members:
在我的gammatone/coeffs.py
中,我有:
namedtuple
生成的代码包含非常通用的docstring,Sphinx的autodoc
模块会提取并包含这些docstring。我宁愿自己对类进行适当的文档化,而不放弃模块其余部分的autodoc
。在
我试过在课前放这样的东西:
"""
.. class:: ERBFilterCoeffs(A0, gain)
:param A0: A0 coefficient
:param gain: Gain coefficient
Magic coefficients.
"""
…但它不会显示在生成的文档中。将它放在类之后会导致它嵌套在泛型类文档下,而不是替换它。在
如何简单地告诉Sphinx(和autodoc
扩展)使用我的文档来处理ERBFilterCoeffs
类,而不是{
实际上根本不需要扩展namedtuple。可以将docstring放在namedtuple之后。这实际上也适用于常量和属性。在
在用namedtuple定义
ERBFilterCoeffs
之后,尝试将该doc字符串分配给ERBFilterCoeffs.__doc__
,怎么样?在编辑:好的,那这个怎么样:
一般来说,我更喜欢对生成的内容进行更好的控制,而不是将}。我不会在这里添加
:members:
指令添加到automodule
中。因此,我建议使用.. autoclass:: ERBFilterCoeffs
显式地记录{:members:
指令,因为这将包括namedtuple
为每个字段创建的非常通用的默认文档。相反,我将在docstring中使用.. py:attribute:: ...
元素,您可以使用特殊的#:
注释将其放在类定义之前:相关问题 更多 >
编程相关推荐