Gibt es bei Sphinx eine Möglichkeit, Parameter zu dokumentieren und zu deklarieren?

Question

Ich ziehe jeden Parameter (je nach Bedarf) auf der gleichen Linie zu dokumentieren, wo ich die Parameter, um zu erklären D.R.Y.

anwenden Wenn ich Code wie dieses:

def foo(
     flab_nickers, # a series of under garments to process 
     has_polka_dots=False, 
     needs_pressing=False # Whether the list of garments should all be pressed 
    ): 
    ... 

Wie kann ich Wiederholung vermeiden die Parameter in der Doc-Zeichenfolge und behalten Sie die Parameter Erklärungen?

Ich möchte vermeiden:

def foo(
     flab_nickers, # a series of under garments to process 
     has_polka_dots=False, 
     needs_pressing=False # Whether the list of garments should all be pressed 
    ): 
    '''Foo does whatever. 

    * flab_nickers - a series of under garments to process 
    * needs_pressing - Whether the list of garments should all be pressed. 
     [Default False.] 

in Python dies möglich ist 2.6 oder Python 3 mit irgendeiner Art von Dekorateur Manipulation? Gibt es einen anderen Weg?

Answer 1

Ich würde dies tun.

Beginnen mit diesem Code.

def foo(
     flab_nickers, # a series of under garments to process 
     has_polka_dots=False, 
     needs_pressing=False # Whether the list of garments should all be pressed 
    ): 
    ... 

ich einen Parser schreiben würde, der die Funktion Parameterdefinitionen packt und baut die folgenden:

def foo(
     flab_nickers, 
     has_polka_dots=False, 
     needs_pressing=False, 
    ): 
    """foo 

    :param flab_nickers: a series of under garments to process 
    :type flab_nickers: list or tuple 
    :param has_polka_dots: default False 
    :type has_polka_dots: bool 
    :param needs_pressing: default False, Whether the list of garments should all be pressed 
    :type needs_pressing: bool 
    """ 
    ... 

, dass einige ziemlich geradlinig regex Verarbeitung der verschiedenen Argumente String-Muster ist in der Dokumentationsvorlage zu füllen .

Viele gute Python-IDEs (zum Beispiel PyCharm) verstehen die Standard-Sphinx-param-Notation und sogar VARs/Methoden im Bereich zu markieren, die nach Meinung der IDE nicht dem deklarierten Typ entsprechen.

Beachten Sie das zusätzliche Komma im Code; das ist nur, um die Dinge konsistent zu machen. Es schadet nicht, und es könnte die Dinge in Zukunft vereinfachen.

Sie können auch versuchen, den Python-Compiler zu verwenden, um einen Syntaxbaum zu erhalten, ihn zu überarbeiten und den Aktualisierungscode auszugeben. Ich habe das für andere Sprachen (nicht für Python) gemacht, also weiß ich ein bisschen darüber, aber ich weiß nicht, wie gut es in Python unterstützt wird.

Auch dies ist eine einmalige Transformation.

Die ursprünglichen Inline-Kommentare in der Funktionsdefinition folgen DRY nicht wirklich, da es sich um einen Kommentar in einer informellen Sprache handelt, der von allen außer den ausgeklügeltsten Tools nicht verwendet werden kann.

Die Sphinx-Kommentare sind näher an DRY, da sie sich in der RST-Auszeichnungssprache befinden, was die Verarbeitung mit normalen Textanalyse-Tools in docutils wesentlich erleichtert.

Es ist nur DRY, wenn Werkzeuge es verwenden können.

Nützliche Links: https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions http://sphinx-doc.org/domains.html#id1

Answer 2

Sie können das nicht ohne einen Vorprozessor, als Kommentare für Python nicht existieren, wenn die Quelle kompiliert wurde. Um Wiederholungen zu vermeiden, entfernen Sie die Kommentare und dokumentieren Sie die Parameter nur im Docstring. Dies ist die Standardmethode zum Dokumentieren Ihrer Argumente.

Answer 3

Anmerkungen sollen dieses Problem in Python zu teilweise adressieren 3:

http://www.python.org/dev/peps/pep-3107/

Ich bin mir nicht sicher, ob gab es eine Arbeit dieser Sphinx noch bei der Anwendung.