In Sphinx, ist es eine Möglichkeit, Parameter zu dokumentieren zusammen mit ihnen zu erklären?

Question

Ich ziehe jeden Parameter zu dokumentieren (je nach Bedarf) auf der gleichen Linie, wo ich die Parameter, um zu erklären a href anwenden <= „http://en.wikipedia.org/wiki/Don't_repeat_yourself“ rel =“ noreferrer "> DRY

Wenn ich Code wie folgt:

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 die Parameter in dem doc-String nicht wiederholen und die Parameter Erklärungen behalten?

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

Ist das möglich in Python 2.6 oder Python 3 mit irgendeiner Art von Dekorateur Manipulation? Gibt es eine andere Möglichkeit?

Answer 1

Ich würde dies tun.

Mit diesem Code starten.

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
   ):
    ...

würde ich einen Parser schreiben, die die Funktion Parameterdefinitionen packen und bauen die folgende:

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
   """
    ...

Das ist etwas ziemlich geradlinig regex Verarbeitung der Muster verschiedene Argumente Zeichenfolge in der Dokumentationsvorlage zu füllen.

Eine Menge guter Python IDEs (zB PyCharm) verstehen die Standard Sphinx param Notation und sogar Flagge Vars / Methoden im Rahmen der IDE denkt an den deklarierten Typ nicht entspricht.

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

Sie können auch versuchen, die Python-Compiler verwenden, um einen Parsing-Baum zu bekommen, überarbeiten und geben Sie den Update-Code. Ich habe dies für andere Sprachen gemacht (nicht Python), so dass ich ein wenig darüber wissen, aber wissen nicht, wie gut unterstützt es in Python ist.

Auch dies ist eine einmalige Transformation.

Das Original in-line Kommentare in der Funktionsdefinition nicht wirklich DRY folgen, weil es sich um ein Kommentar ist, in einer ungezwungenen Sprache und unbrauchbar machen, indem jeder, aber die anspruchsvollsten Werkzeuge.

Die Sphinx Kommentare sind DRY näher, weil sie in der RST-Markup-Sprache sind, so dass sie viel einfacher mit gewöhnlichem Text-Parsing-Tool in docutils zu verarbeiten.

Es ist nur DRY wenn Werkzeuge davon Gebrauch machen 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

Anmerkungen sollen teilweise Lösung dieses Problems in Python 3:

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

Ich bin sicher nicht, wenn es irgendeine Arbeit ist noch diese Sphinx bei der Anwendung.

Answer 3

Sie können das nicht ohne einen Prä-Prozessor, als Kommentare für Python nicht existieren, wenn die Quelle kompiliert wurde. Um zu vermeiden, sich zu wiederholen, entfernen Sie die Kommentare und dokumentieren die Parameter nur in der docstring, das ist der normale Weg, Ihre Argumente zu dokumentieren.