如何使用 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

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

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

的事情

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

Answer 1

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

向 Foo class 添加文档字符串。在该文档字符串中，描述 _fields_ class 变量。也许最简单的方法是简单地逐字包含定义。像这样：

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)]

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

How to document Structure fields in Python using Sphinx

python

ctypes

python-sphinx