Dieser Artikel stammt aus dem Maya-Python-Adventskalender vom 11. Dezember.

Einführung

Eine der Funktionen von Python ist Dokumentationszeichenfolgen.

Es wird als Dokument interpretiert, indem die folgenden Zeichenfolgen in Module, Klassen, Funktionen usw. geschrieben werden.

`python`


def sayhello():
    u"""Hallo und fröhlich Hallo sagen."""
    sys.stdout.write(u"Hallo!")

Wenn Sie es an die Hilfemethode übergeben, wird es formatiert und ausgegeben. Verwenden Sie es also, um herauszufinden, wie die Funktion verwendet wird.

>>> help(sayhello)
Help on function sayhello in module __main__:

sayhello()
Hallo und fröhlich Hallo sagen

Natürlich werden auch Standardmodule beschrieben.

>>> import os
>>> help(os.path.abspath)
Help on function abspath in module ntpath:

abspath(path)
    Return the absolute version of a path.

Überprüfungsumgebung

Windows10 Python 2.7.12 PyCharm 2016.3 Sphinx 1.5 Maya 2016 Extension2

Probleme haben wir

Wir verwalten eine Vielzahl von Modulen, Methoden und Klassen als gemeinsam genutzte Bibliotheken. Selbst zu diesem Zeitpunkt ist die Anzahl der Funktionen zu groß, um sich an alles zu erinnern. Von diesen funktioniert das Maya-Paket nur mit Maya-integriertem Python. Es gibt andere integrierte Python-abhängige Pakete, aber dieses Mal beschränken wir uns auf Maya.

stu/
  __init__.py
  maya/
    __init__.py
    skin.py
Viele andere ...
  path.py
  pyside.py
Viele andere ...

Förderung der Verwendung gemeinsam genutzter Bibliotheken
Vermeiden Sie die Neuentwicklung von Rädern

Aus den beiden oben genannten Gründen besteht ein Bedarf an einem System, das mit der gewünschten Funktion leicht durchsucht werden kann und eine hohe Sichtbarkeit für die Methodenargumentspezifikationen aufweist.

Da ich auch einen Testcode erstellt habe, kann ich anhand des Testcodes verstehen, wie man ihn verwendet, aber natürlich weiß ich nicht, wie die aktuellen Spezifikationen erstellt werden, und der Testcode ist überhaupt nicht gut. Oft genug.

Die Geschichte lautet also "Lassen Sie uns eine Notiz auf dem Dokumentstring richtig hinterlassen", aber ich selbst schreibe sie nicht sehr aggressiv.

Menschen brauchen Motivation zum Handeln.

Wie motivierst du dich? Deshalb möchte ich den Docstring noch einmal überdenken.

Probleme nicht gepflegt

Wie in PEP8 erwähnt, ist das Schlimmste, dass der Code und die Kommentare nicht übereinstimmen. Ich weiß nicht, welches richtig ist. Es ist besser, keine Kommentare zu schreiben, die nicht gepflegt werden.

Warum schreibst du nicht einfach solche Ausreden? Ist es nicht einfach so, weil es keinen Nutzen für mich gibt?

Python entwickelt sich von Tag zu Tag weiter. Ab Python 3.5 wurde eine Funktion zum Definieren des Typs einer Variablen namens Type Hints (PEP484) hinzugefügt. Es ist möglich, die Arten von Argumenten und Rückgabewerten zu definieren. Wenn der Editor dies unterstützt, können die Methoden der zurückgegebenen Variablen als Kandidaten angezeigt werden. In PyCharm Type Hinting Geben Sie als Funktion Hinweise von Python3.5 ein und beschreiben Sie diese in docstrings Es scheint es zu unterstützen.

Dies scheint ein Anreiz zu sein, den Docstring beizubehalten.

Jetzt möchte ich die folgende Überprüfung durchführen und das HTML-Dokument abrufen, während ich docstring bequem verwende.

PyCharm-Typ-Hinweis
Durchsuchen Sie Dokumente in HTML mit Sphinx

Überprüfen Sie den Typhinweis

Es scheint, dass Type Hints in Python 3.5 eingeführt wurde, daher scheint es eine Möglichkeit zu geben, dies in einigen Kommentaren auszudrücken. Da es jedoch in Python 2 nicht verwendet werden kann, wird es abgelehnt.

Stellen Sie zunächst wie gewohnt sicher, dass Project Interpreter Mayapy ist. Wenn dies vernachlässigt wird, funktioniert es nicht, selbst wenn der Pymeltyp definiert ist.

Definieren wir den Rückgabewert der Funktion. Versuchen Sie, SkinCluster mit `rtype `anzugeben. Versuchen Sie also, die Funktion aufzurufen und in einer Variablen zu speichern.

Wenn Sie eine Methode aus dieser Variablen eingeben, ist die Methode des skinCluster-Objekts ein Kandidat. Natürlich die Methode der Elternklasse. Toll···

Jetzt gibt es keinen Grund, rtype nicht einfach zu schreiben.

Sphinx validieren

Python verfügt über mehrere Mechanismen zum automatischen Generieren von HTML-Dokumenten aus dem Quellcode. In letzter Zeit konzentriert es sich jedoch auch auf die Unterstützung anderer Programmiersprachen als Python Sphinx. /de/1.5/) ist wahrscheinlich die häufigste. Die offizielle Dokumentation für Python selbst ist ebenfalls Sphinx. Es scheint vielmehr, dass es zu diesem Zweck entwickelt wurde.

Sphinx generiert automatisch ein Dokument, damit Sie nach den in der Dokumentzeichenfolge geschriebenen Informationen suchen können.

Installieren Sie vorerst Sphinx mit Pip.

"C:\Program Files\Autodesk\Maya2016\bin\mayapy.exe" -m pip install sphinx --user

Da Sphinx auch mit PyCharm verwendet werden kann, geben Sie das Dokumentverzeichnis an. Diesmal ist es C: \ sample \ sphinx.

Führen Sie Sphinx Quickstart aus, um interaktiv eine Konfigurationsdatei zu erstellen. Grundsätzlich ist die Sprache auf ja eingestellt und der Rest ist standardmäßig in Ordnung. (Entschuldigung für die grobe Erklärung)

Nur aus diesem Grund sind Dokumentzeichenfolgen irrelevant und erstellen HTML nur aus einer Textdatei (.rst) im reStructuredText-Format, also sphinx-apidoc Invocation-of-sphinx-apidoc) wird separat verwendet, um eine erste Datei zu generieren, die API-Dokumentation aus dem Quellcode generiert. Es wird in der Befehlszeile ausgeführt.

%USERPROFILE%\AppData\Roaming\Python\Scripts\sphinx-apidoc.exe Bibliothekspfad-o C:\sample\sphinx

Jetzt bist du bereit. Als nächstes folgt die Ausführung der Dokumentgenerierung. Kehren Sie zu PyCharm zurück und erstellen Sie eine neue Konfiguration aus Run / Debug-Konfigurationen. Die Aufgabe Python docs / Sphinx ist ordnungsgemäß vorbereitet ... Geben Sie die Ein- und Ausgabe an und fertig. Ich denke, Interpreter ist eine Therapie, aber bitte beachten Sie, dass Sphinx das Modul in ein Dokument importiert und die Dokumentzeichenfolgen abruft. In normalem Python tritt daher ein Importfehler auf und die Dokumentation schlägt ebenfalls fehl.

Also, lauf wie gewohnt. C: \ sample \ sphinx \ _ build \ index.html (und viele andere) sollte generiert werden.

Öffnen Sie index.html. Im Standardzustand wird HTML generiert, aber wir suchen danach.

Oh, das Ergebnis kam heraus. (Einer ist Müll)

Oh! Der in der Dokumentzeichenfolge beschriebene Rückgabetyp wird ordnungsgemäß beschrieben.

Zusammenfassung

Viel Know-how für Docstrings kam aus dem Internet. Es scheint einige Kandidaten für das Markup-Format zu geben, aber vorerst werde ich es in reStructuredText schreiben, dem Standard-Python-Markup. Ist Markdown wie bei diesem in Qiita geschriebenen Satz der De-facto-Standard für Markup-Sprachen in der Welt? Ich bin ein wenig besorgt, weil es nicht überraschend ist, aber ich muss nicht zu dem Schluss kommen, weil der Zweck nicht in erster Linie ein Dokument mit einer so komplizierten Struktur ist. Ich werde zu einem anderen Zeitpunkt darüber nachdenken.

Sphinx fühlt sich ein bisschen schwierig an, auf der Kommandozeile zu laufen, aber wenn man es auf PyCharm ausführt, verbirgt sich der größte Teil des Ärgers. Eigentlich habe ich viele Versuche und Irrtümer wiederholt, daher ist es ein wenig enttäuschend, dass es ein Attentat sein wird, wenn ich PyCharm als Ergebnis verwende.

Am Ende war das Ergebnis wieder das beste von PyCharm.

Referenz

Hinweis auf Mastering-Typ in PyCharm Einfache Dokumentation in Sphinx mit PyCharm (IntelliJ) schreiben

[PYTHON] Dokumentationszeichenfolge überdenken