Skip to main content
 首页 » 编程设计

python之如何使用 Sphinx 在 Python 中记录结构字段

2025年04月02日15tintown

我有以下方式声明的 python 类:

class Foo(Structure): 
    _fields_ = [ 
        ("vr", c_double), 
        ("vi", c_double), 
        ("vm", c_float), 
        ("va", c_float)] 

它们是 Structure 的子类,因为我正在使用 ctypes 来包装 C DLL,而这些是 C 结构的镜像。我不知道如何为这些生成文档。自动生成的文档非常丑陋且无用: VA 结构/工会成员 六 结构/工会成员 虚拟机 结构/工会成员 虚拟现实 结构/联合成员

有人知道我如何定义这些吗?

我只是想澄清一下 _fields_ 实际上并不存在。这是 ctypes 的一项特殊功能,它提供了一种声明成员的方式,您可以使用 C 结构来声明成员。因此,如果我实例化对象:foo = Foo() 那么我永远不会访问 _fields_ 而是直接访问成员,就好像它们只是被声明为普通实例变量一样。因此,使用上面的实例,要访问 vr,我会做类似 print foo.vr 的事情。

让我感到困惑的是我想添加对这些变量的描述。自动生成将它们称为“结构/联合成员”,这是有道理的,因为它们是结构的成员,但我想添加更具描述性和有用的描述。例如,我想添加一个注释,“vm”是幅度,“va”是角度。

请您参考如下方法:

如果删除 automodule 指令的 :undoc-members: 选项,不需要的自动生成的文档就会消失。


将文档字符串添加到 Foo 类。在该文档字符串中,描述了 _fields_ 类变量。也许最简单的方法是简单地逐字包含定义。像这样:

class Foo(Structure): 
    """ 
    This class is used to... 
 
    The ``_fields_`` class variable is defined as follows:: 
 
      _fields_ = [ 
         ("vr", c_double), 
         ("vi", c_double), 
         ("vm", c_float), 
         ("va", c_float)] 
    """ 
 
    _fields_ = [ 
        ("vr", c_double), 
        ("vi", c_double), 
        ("vm", c_float), 
        ("va", c_float)] 

这是另一种可能更接近您想要的方法:

class Foo(Structure): 
    """ 
    This class is used to... 
 
    Instances of this class have the following members: 
 
    * ``vr`` (type: c_double): whatever 
    * ``vi`` (type: c_double): something 
    * ``vm`` (type: c_float): magnitude  
    * ``va`` (type: c_float): angle 
    """ 
 
    _fields_ = [ 
        ("vr", c_double), 
        ("vi", c_double), 
        ("vm", c_float), 
        ("va", c_float)] 

另一种选择(使用 info fields ):

class Foo(Structure): 
    """ 
    This class is used to... 
 
    :ivar vr: whatever 
    :vartype vr: c_double 
    :ivar vi: something 
    :vartype vi: c_double 
    :ivar vm: magnitude 
    :vartype vm: c_float 
    :ivar va: angle 
    :vartype va: c_float 
    """ 
 
    _fields_ = [ 
        ("vr", c_double), 
        ("vi", c_double), 
        ("vm", c_float), 
        ("va", c_float)]