MEP10: Docstring-Konsistenz #

Status #

Fortschritt

Dies ist immer noch eine andauernde Anstrengung

Branches und Pull-Requests #

Zusammenfassung #

Matplotlib hat eine große Inkonsistenz zwischen Docstrings. Dies erschwert nicht nur das Lesen der Dokumentation, sondern auch die Mitwirkenden, da sie nicht wissen, welchen Spezifikationen sie folgen sollen. Es sollte eine klare Docstring-Konvention geben, die konsequent befolgt wird.

Die Organisation der API-Dokumentation ist schwer nachzuvollziehen. Einige Seiten, wie Pyplot und Axes, sind riesig und schwer zu durchsuchen. Stattdessen sollte es kurze zusammenfassende Tabellen geben, die auf eine ausführliche Dokumentation verweisen. Darüber hinaus sind einige der Docstrings selbst ziemlich lang und enthalten redundante Informationen.

Das Erstellen der Dokumentation dauert lange und verwendet make.py eher ein Skript als ein Makefile.

Detaillierte Beschreibung #

Seit matplotlib mit der Verwendung von Sphinx begonnen hat, gibt es eine Reihe neuer Tools und Konventionen, die das Leben einfacher machen. Das Folgende ist eine Liste vorgeschlagener Änderungen an Docstrings, von denen die meisten diese neuen Funktionen betreffen.

Numpy Docstring-Format #

Numpy Docstring-Format : Dieses Format unterteilt den Docstring in klare Abschnitte mit jeweils unterschiedlichen Parsing-Regeln, die den Docstring sowohl als Rohtext als auch als HTML leicht lesbar machen. Wir könnten Alternativen in Betracht ziehen oder unsere eigenen erfinden, aber dies ist eine gute Wahl, da es in der Numpy/Scipy-Community gut verwendet und verstanden wird.

Querverweise #

Die meisten Docstrings in Matplotlib verwenden explizite "Rollen", wenn sie auf andere Elemente verlinken, zum Beispiel: :func:`myfunction`. Ab Sphinx 0.4 gibt es eine "default_role", die auf "obj" gesetzt werden kann und polymorph mit einem beliebigen Python-Objekt verknüpft wird. `myfunction`Dies ermöglicht es einem, stattdessen zu schreiben . Dadurch sind Docstrings als Rohtext viel einfacher zu lesen und zu bearbeiten. Darüber hinaus ermöglicht Sphinx die Einstellung eines aktuellen Moduls, sodass Links wie `~matplotlib.axes.Axes.set_xlim` als `~axes.Axes.set_xlim`.

Signaturen überschreiben #

Viele Methoden in matplotlib verwenden die *argsand - **kwargsSyntax, um die von der Funktion akzeptierten Schlüsselwortargumente dynamisch zu verarbeiten oder an eine andere Funktion zu delegieren. Als Signatur in der Dokumentation ist dies jedoch oft nicht sinnvoll. Aus diesem Grund beinhalten viele Matplotlib-Methoden so etwas wie:

def annotate(self, *args, **kwargs):
    """
    Create an annotation: a piece of text referring to a data
    point.

    Call signature::

      annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)
    """

Dies kann von Sphinx nicht analysiert werden und ist im Rohtext ziemlich ausführlich. Ab Sphinx 1.1 autodoc_docstring_signatureextrahiert Sphinx, wenn der Konfigurationswert auf True gesetzt ist, eine Ersatzsignatur aus der ersten Zeile des Dokumentstrings, wodurch Folgendes möglich ist:

def annotate(self, *args, **kwargs):
    """
    annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)

    Create an annotation: a piece of text referring to a data
    point.
    """

Die explizite Signatur ersetzt die tatsächliche Python-Signatur in der generierten Dokumentation.

Verlinken statt duplizieren #

Viele der Docstrings enthalten lange Listen akzeptierter Schlüsselwörter, indem sie zur Ladezeit Dinge in den Docstring interpolieren. Dadurch werden die Docstrings sehr lang. Da diese Tabellen in vielen Dokumentzeichenfolgen gleich sind, fügt es viele redundante Informationen in die Dokumente ein – insbesondere ein Problem in der gedruckten Version.

Diese Tabellen sollten in Docstrings für Funktionen verschoben werden, deren einziger Zweck die Hilfe ist. Die Docstrings, die auf diese Tabellen verweisen, sollten auf sie verlinken, anstatt sie wörtlich einzufügen.

Autosummary-Erweiterung #

Die Autosummary-Erweiterung von Sphinx sollte verwendet werden, um Übersichtstabellen zu generieren, die auf separate Seiten der Dokumentation verlinken. Einige Klassen, die viele Methoden haben (zB Axes), sollten mit einer Methode pro Seite dokumentiert werden, während kleinere Klassen alle ihre Methoden zusammen haben sollten.

Beispiele mit Links zu relevanter Dokumentation #

Die Beispiele sind zwar hilfreich bei der Veranschaulichung der Verwendung einer Funktion, verweisen jedoch nicht auf die relevanten Dokumentzeichenfolgen. Dies könnte behoben werden, indem den Beispielen Dokumentzeichenfolgen auf Modulebene hinzugefügt werden und diese Dokumentzeichenfolge dann in den geparsten Inhalt auf der Beispielseite aufgenommen wird. Diese Docstrings könnten leicht Verweise auf andere Teile der Dokumentation enthalten.

Dokumentation mit help() im Vergleich zu einem Browser #

Die Verwendung von Sphinx-Markup in der Quelle ermöglicht gut aussehende Dokumente in Ihrem Browser, aber das Markup lässt auch den Rohtext, der mit help() zurückgegeben wird, schrecklich aussehen. Eines der Ziele der Verbesserung der Docstrings sollte darin bestehen, beide Methoden des Zugriffs auf die Dokumente gut aussehen zu lassen.

Implementierung #

  1. Die numpydoc-Erweiterungen sollten für Matplotlib aktiviert werden. Es stellt sich die wichtige Frage, ob diese in den Matplotlib-Quellbaum aufgenommen oder als Abhängigkeit verwendet werden sollten. Die Installation von Numpy reicht nicht aus, um die numpydoc-Erweiterungen zu erhalten – es ist ein separater Installationsvorgang. Soweit sie eine Anpassung an unsere Bedürfnisse erfordern, sollten wir uns in jedem Fall bemühen, diese Änderungen vorab einzureichen und sie nicht zu forken.

  2. Gehen Sie alle Dokumentzeichenfolgen manuell durch und aktualisieren Sie sie auf das neue Format und die neuen Konventionen. Die Aktualisierung der Querverweise (von `:func:`myfunc`bis `func`) kann halbautomatisch erfolgen. Dies ist eine Menge anstrengender Arbeit, und vielleicht sollte diese Arbeit pro Modul aufgeteilt werden, damit kein einzelner Entwickler dadurch überlastet wird.

  3. Reorganisieren Sie die API-Dokumente mithilfe von Autosummary und sphinx-autogen. Dies sollte hoffentlich nur minimale Auswirkungen auf die narrative Dokumentation haben.

  4. Ändern Sie den Beispielseitengenerator ( gen_rst.py) so, dass er den Modul-Docstring aus dem Beispiel extrahiert und in einen nicht wörtlichen Teil der Beispielseite einfügt.

  5. Verwenden Sie diese Option sphinx-quickstart, um ein Sphinx-Makefile im neuen Stil zu erstellen. Die folgenden Merkmale in der aktuellen make.pymüssen auf andere Weise angegangen werden:

    • Kopieren einiger statischer Inhalte

    • Festlegen eines "kleinen" Builds (nur PNG-Dateien mit niedriger Auflösung für Beispiele)

Die Schritte 1, 2 und 3 sind voneinander abhängig. 4 und 5 können unabhängig voneinander durchgeführt werden, obwohl 5 eine gewisse Abhängigkeit von 3 hat.

Abwärtskompatibilität #

Da es sich dabei hauptsächlich um Docstrings handelt, sollte es nur minimale Auswirkungen auf die Abwärtskompatibilität geben.

Alternativen #

Noch keine diskutiert.