Wie Strukturfelder in Python mit Sphinx

Question

Ich habe Python Klassen deklariert in der folgenden Art und Weise dokumentieren:

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

Sie Subklassen von Structure sind, weil ich ctypes zu wickeln eine C-DLL verwende und diese sind die Spiegel von die C-Strukturen. Ich kann nicht herausfinden, wie man Dokumentation für diese erzeugt. Die automatisch generierte Dokumentation ist sehr hässlich und nutzlos: va Structure/Union member vi Structure/Union member vm Structure/Union member vr Structure/Union member

Hat jemand eine Idee, wie ich diese definieren kann?

Ich wollte nur klarstellen, dass _fields_ Art von tatsächlich nicht existiert. Es ist ein besonderes Feature von ctypes, das eine Möglichkeit bietet, Member so zu deklarieren, dass Sie mit einer C-Struktur ausgerichtet werden können. Also, wenn ich das Objekt instanziieren: foo = Foo() dann würde ich niemals auf _fields_ sondern die Mitglieder direkt zugreifen, als ob sie nur als normale Instanzvariablen deklariert wurden. Also, mit der obigen Instanz, um auf vr zuzugreifen, würde ich etwas wie print foo.vr tun.

Was mich hier stolpert ist, dass ich Beschreibungen dieser Variablen hinzufügen möchte. Die automatische Generierung nennt sie "Struktur-/Union-Mitglieder", was sinnvoll ist, da sie Mitglieder einer Struktur sind, aber ich möchte eine anschaulichere und nützlichere Beschreibung hinzufügen. Zum Beispiel möchte ich eine Notiz hinzufügen, dass "vm" ist Magnitude und "va" ist Winkel.

Answer 1

Die nicht automatisch generierte Dokumentation verschwindet, wenn die :undoc-members:-Option zu der automodule-Anweisung entfernt wird.

---

eine docstring zum Foo Klasse hinzufügen. Beschreiben Sie in diesem Docstring die Klassenvariable _fields_. Vielleicht ist der einfachste Weg, dies zu tun, einfach die Definition wortwörtlich aufzunehmen. Etwas wie folgt aus:

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

Hier ist eine andere Art und Weise tun, die näher sein könnte, was Sie wollen:

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

noch eine weitere Alternative (mit 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)]