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。

之类的操作

我在这里绊倒的是我想要添加这些变量的描述。自动生成称他们为＆＃34;结构/工会成员＆＃34;这是有道理的，因为它们是结构的成员，但我想添加更具描述性和有用的描述。例如，我想添加一个注释＆＃34; vm＆＃34;是规模和＆＃34; va＆＃34;是角度。

Answer 1

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

将文档字符串添加到Foo类。在该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)]

这是另一种可能更接近你想要的方式：

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

1 个答案: