如何使用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成员 vi Structure/Union成员 vm Structure/Union成员 vr Structure/Union成员 有人有任何想法如何定义这些吗？

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

这里让我感到困惑的是，我想添加这些变量的描述。自动生成程序将它们称为“结构/联合成员”，这很有道理，因为它们是结构的成员，但我想添加更详细和有用的描述。例如，我想添加一个注释，说明“vm”代表幅度，“va”代表角度。

- zaknotzach

---

Foo类应该有一个文档字符串。在这个文档字符串中，你可以描述_fields_变量。也许可以直接包含它的定义原文。这是我能想到的。 - mzjn

“我想添加这些变量的描述”。你可以这样做，我已经提供了示例。到底是什么让你困扰？ - mzjn

我最近有很多工作要忙，等我测试过你的建议并确认它们有效之后，我会很高兴地接受你的答案。谢谢你的帮助。 - zaknotzach

你使用:undoc-members:选项到automodule吗？因为如果我使用它，我会得到自动生成的输出，而你不喜欢。 - mzjn

搞定了！移除 :undoc-members: 后，所有自动生成的东西都消失了，现在我可以自由地覆盖它。这有点烦人，因为这意味着我现在必须去记录每一件事情，而不是逐步完成，但至少现在已经处理好了。请随意将其放入答案中，我会接受它。 - zaknotzach

Answer 1

如果从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)]

另一种选择（使用信息字段）：

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

- mzjn

---

但是，为了澄清，_fields_ 是 ctypes/structure 中使用的特殊成员。基本上，您正在定义该类的成员。因此，我可以在 Foo 类的实例中像这样访问它们：foo.vm = 0.5。 - zaknotzach

我看到你更新了问题。 “但我想添加更详细和有用的描述。例如，我想添加一个注释，指出“vm”是幅度，“va”是角度。”然后，只需将描述性和有用的描述添加到文档字符串中即可。或者有什么问题吗？ - mzjn

谢谢您的反馈，我会再次测试。我相信当我刚开始尝试时，我已经尝试过了，但是我所做的某些事情似乎没有起作用。 - zaknotzach