Auslassen (oder formatieren) des Wertes einer Variablen beim Dokumentieren mit Sphinx

Question

Ich dokumentiere gerade ein ganzes Modul mit autodoc. Ich definiere jedoch mehrere Variablen auf der Modulebene, die lange Listen oder Dicts enthalten. Sie sind in der Dokumentation zusammen mit den Werten enthalten, und die Werte sind unformatiert, so dass es wie ein 10-Zeilen-Chaos aussieht. Was ich will, ist für die Docstring dieser Variablen enthalten sein, aber für die Werte weggelassen oder zumindest schön formatiert.

Ich habe versucht, die Variable aus automodule Richtlinie auszunehmen und es so hinzufügen:

.. automodule:: foo.bar 
    :members: 
    :exclude-members: longstuff 

    .. py:data:: longstuff 

Dies ergab, dass nur der Variablenname enthalten war, während sowohl die docstring und der Wert von longstuff nicht waren in der Dokumentation vorhanden.

Wie kann ich den Docstring behalten und den Wert (oder haben Sie es schön formatiert) zur gleichen Zeit loswerden? Danke im Voraus.

Answer 1

Es gibt keine einfache Konfigurationseinstellung zum Auslassen von Werten von Modulebenenvariablen in der Ausgabe. Aber Sie können es tun, indem Sie die Methode in autodoc.py ändern. Der entscheidende Linie in dieser Methode ist

self.add_line(u' :annotation: = ' + objrepr, '<autodoc>') 

wo objrepr Der Wert ist.

Der folgende Affe Patch hinzugefügt conf.py Werke für mich:

from sphinx.ext.autodoc import ModuleLevelDocumenter, DataDocumenter 

def add_directive_header(self, sig): 
    ModuleLevelDocumenter.add_directive_header(self, sig) 
    # Rest of original method ignored 

DataDocumenter.add_directive_header = add_directive_header