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

Question

我有如下声明的python类：

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

它们是Structure的子类，因为我使用ctypes来包装一个C DLL，这些是C结构的镜像。我不知道如何生成这些文档。自动生成的文档非常丑陋和无用： va Structure/Union member vi Structure/Union member vm Structure/Union member vr Structure/Union member

有人知道我怎么定义这些吗？在

我只是想澄清一下{}实际上并不存在。它是ctypes的一个特殊功能，它提供了一种声明成员的方法，可以与C结构对齐。因此，如果我实例化对象：foo = Foo()，那么我永远不会访问_fields_，而是直接访问成员，就像它们只是被声明为普通实例变量一样。{{cd8>要使用上面的实例来做一些事情。在

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

Answer 1

如果删除了automodule指令的:undoc-members:选项，则不需要的自动生成文档将消失。在

---

向Foo类添加docstring。在该docstring中，描述_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)]

下面是另一种更接近您想要的方法：

^{pr2}$

另一种选择（使用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)]