Dokumentation schreiben #

Erste Schritte #

Allgemeine Dateistruktur #

Die gesamte Dokumentation wird aus der doc/. Das doc/ Verzeichnis enthält Konfigurationsdateien für Sphinx und reStructuredText ( ReST ; .rst)-Dateien, die in Dokumentationsseiten gerendert werden.

Die Dokumentation wird auf drei Arten erstellt. Zuerst wird die API-Dokumentation ( doc/api) von Sphinx aus den Docstrings der Klassen in der Matplotlib-Bibliothek erstellt. Mit Ausnahme von doc/api/api_changes/werden .rstDateien in doc/apierstellt, wenn die Dokumentation erstellt wird. Siehe Schreiben von Docstrings weiter unten.

Zweitens werden die Inhalte von doc/plot_types, doc/galleryund von der Sphinx-Galerie aus Python-Dateien in , und doc/tutorialsgeneriert . Diese Quellen bestehen aus Python-Skripten, in deren Kommentare eine ReST- Dokumentation integriert ist. Siehe Schreibbeispiele und Tutorials weiter unten.plot_types/examples/tutorials/

Drittens hat Matplotlib narrative Dokumente, die in ReST in Unterverzeichnissen von doc/users/. Wenn Sie eine neue Dokumentation hinzufügen möchten, die für eine .rstDatei geeignet ist, statt für ein Galerie- oder Tutorial-Beispiel, wählen Sie ein geeignetes Unterverzeichnis, um sie dort abzulegen, und fügen Sie die Datei dem Inhaltsverzeichnis des index.rstUnterverzeichnisses hinzu. Siehe Schreiben von ReST-Seiten weiter unten.

Notiz

.rstBearbeiten Sie die Dateien in doc/plot_types, doc/gallery, doc/tutorialsund doc/api (außer doc/api/api_changes/) nicht direkt . Sphinx generiert Dateien in diesen Verzeichnissen neu, wenn die Dokumentation erstellt wird.

Einrichten des Dokument-Builds Nr .

Die Dokumentation für Matplotlib wird aus reStructuredText ( ReST ) mit dem Dokumentationsgenerierungstool Sphinx generiert.

Um die Dokumentation zu erstellen, müssen Sie Matplotlib für die Entwicklung einrichten . Beachten Sie insbesondere die zusätzlichen Abhängigkeiten , die zum Erstellen der Dokumentation erforderlich sind.

Erstellen der Dokumente #

Die Dokumentationsquellen befinden sich im doc/Verzeichnis im Kofferraum. Die Konfigurationsdatei für Sphinx ist doc/conf.py. Es steuert, welche Verzeichnisse Sphinx analysiert, wie die Dokumente erstellt werden und wie die Erweiterungen verwendet werden. Um die Dokumentation im HTML-Format zu erstellen, cd hinein doc/und führen Sie Folgendes aus:

make html

Andere nützliche Aufrufe umfassen

# Delete built files.  May help if you get errors about missing paths or
# broken links.
make clean

# Build pdf docs.
make latexpdf

Die SPHINXOPTSVariable ist standardmäßig so eingestellt, dass sie die vollständigen Dokumente erstellt, aber mit dem Exit-Status 1 beendet wird, wenn Warnungen vorhanden sind. Verwenden Sie zum Deaktivieren-W --keep-going

make SPHINXOPTS= html

Sie können die OVariable verwenden, um zusätzliche Optionen festzulegen:

  • make O=-j4 htmlführt einen parallelen Build mit 4 Prozessen aus.

  • make O=-Dplot_formats=png:100 htmlspeichert Zahlen in niedriger Auflösung.

  • make O=-Dplot_gallery=0 htmlüberspringt den Aufbau der Galerie.

Mehrere Optionen können kombiniert werden, zB .make O='-j4 -Dplot_gallery=0' html

Legen Sie unter Windows die Optionen als Umgebungsvariablen fest, z.

set SPHINXOPTS= & set O=-j4 -Dplot_gallery=0 & make html

Lokal erstellte Dokumente werden angezeigt #

Die erstellten Dokumente sind im Ordner verfügbar build/html. Eine Verknüpfung zum Öffnen in Ihrem Standardbrowser ist:

make show

Schreiben von ReST-Seiten #

Die meiste Dokumentation befindet sich entweder in den Docstrings einzelner Klassen und Methoden, in expliziten .rstDateien oder in Beispielen und Tutorials. All diese verwenden die ReST- Syntax und werden von Sphinx verarbeitet .

Der Sphinx reStructuredText Primer ist eine gute Einführung in die Verwendung von ReST. Ausführlichere Informationen finden Sie in der reStructuredText-Referenzdokumentation .

Dieser Abschnitt enthält zusätzliche Informationen und Konventionen, wie ReST in der Matplotlib-Dokumentation verwendet wird.

Formatierungs- und Stilkonventionen #

Es ist sinnvoll, sich um Konsistenz in der Matplotlib-Dokumentation zu bemühen. Hier sind einige Formatierungs- und Stilkonventionen, die verwendet werden.

Abschnittsformatierung #

Verwenden Sie für alles außer Kapiteln der obersten Ebene für Abschnittstitel, z. B. stattUpper lowerPossible hangupsPossible Hangups

Unser Ziel ist es, den Empfehlungen aus der Python-Dokumentation und der Sphinx reStructuredText-Dokumentation für Abschnitts-Markup-Zeichen zu folgen, d. h.:

  • #mit Überstreichung, für Teile. Dies ist dem Haupttitel in vorbehalten index.rst. Alle anderen Seiten sollten mit "Kapitel" oder niedriger beginnen.

  • *mit Überstrich, für Kapitel

  • =, für Abschnitte

  • -, für Unterabschnitte

  • ^, für Unterabschnitte

  • ", für Absätze

Dies kann in bestehenden Dokumenten noch nicht einheitlich angewendet werden.

Funktionsargumente #

Auf Funktionsargumente und Schlüsselwörter innerhalb von Dokumentzeichenfolgen sollte mithilfe der *emphasis*Rolle verwiesen werden. Dadurch bleibt die Dokumentation von Matplotlib mit der Dokumentation von Python konsistent:

Here is a description of *argument*

Verwenden Sie nicht :`default role`

Do not describe `argument` like this.  As per the next section,
this syntax will (unsuccessfully) attempt to resolve the argument as a
link to a class or method in the library.

noch die ``literal``Rolle:

Do not describe ``argument`` like this.

Verweis auf andere Dokumente und Abschnitte #

Sphinx erlaubt interne Verweise zwischen Dokumenten.

Dokumente können mit der :doc:Richtlinie verknüpft werden:

See the :doc:`/users/installing/index`

See the tutorial :doc:`/tutorials/introductory/quick_start`

See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`

wird gerendert als:

Siehe Installation

Siehe Tutorial Schnellstartanleitung

Siehe das Beispiel Einfaches Diagramm

Abschnitten können auch Referenznamen gegeben werden. Zum Beispiel vom Installationslink :

.. _clean-install:

How to completely remove Matplotlib
===================================

Occasionally, problems with Matplotlib can be solved with a clean...

und verweisen Sie mit der Standardreferenzsyntax darauf:

See :ref:`clean-install`

wird den folgenden Link geben: So entfernen Sie Matplotlib vollständig

Um die interne Konsistenz bei Abschnittsbezeichnungen und Verweisen zu maximieren, verwenden Sie durch Bindestriche getrennte, beschreibende Bezeichnungen für Abschnittsverweise. Denken Sie daran, dass Inhalte später möglicherweise neu organisiert werden. Vermeiden Sie daher Namen auf oberster Ebene in Verweisen wie useroder devel oder faq, sofern dies nicht erforderlich ist, da beispielsweise die FAQ "Was ist ein Backend?" könnte später Teil des Benutzerhandbuchs werden, daher die Bezeichnung:

.. _what-is-a-backend:

ist besser als:

.. _faq-backend:

Da Unterstriche von Sphinx selbst häufig verwendet werden, verwenden Sie außerdem Bindestriche, um Wörter zu trennen.

Verweis auf anderen Code #

Um auf andere Methoden, Klassen oder Module in Matplotlib zu verlinken, können Sie zum Beispiel Backticks verwenden:

`matplotlib.collections.LineCollection`

generiert einen Link wie diesen: matplotlib.collections.LineCollection.

Hinweis: Wir verwenden die Sphinx-Einstellung , damit Sie keine Qualifizierer wie , , und dergleichen verwenden müssen.default_role = 'obj':class::func::meth:

Oft möchten Sie nicht den vollständigen Paket- und Modulnamen anzeigen. Solange das Ziel eindeutig ist, kann man sie einfach weglassen:

`.LineCollection`

und der Link funktioniert immer noch: LineCollection.

Wenn es mehrere Codeelemente mit demselben Namen gibt (z. B. plot()eine Methode in mehreren Klassen), müssen Sie die Definition erweitern:

`.pyplot.plot` or `.Axes.plot`

Diese werden als pyplot.plotoder angezeigt Axes.plot. Um trotzdem nur das letzte Segment anzuzeigen, können Sie eine Tilde als Präfix hinzufügen:

`~.pyplot.plot` or `~.Axes.plot`

wird als plotoder gerendert plot.

Andere Pakete können auch über intersphinx verlinkt werden :

`numpy.mean`

wird diesen Link zurückgeben: numpy.mean. Dies funktioniert für Python, Numpy, Scipy und Pandas (vollständige Liste ist in doc/conf.py). Wenn die externe Verknüpfung fehlschlägt, können Sie die vollständige Liste der referenzierbaren Objekte mit den folgenden Befehlen überprüfen:

python -m sphinx.ext.intersphinx 'https://docs.python.org/3/objects.inv'
python -m sphinx.ext.intersphinx 'https://numpy.org/doc/stable/objects.inv'
python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/scipy/objects.inv'
python -m sphinx.ext.intersphinx 'https://pandas.pydata.org/pandas-docs/stable/objects.inv'

Einschließlich Figuren und Dateien #

Bilddateien können mit der image::Direktive direkt in Seiten eingebunden werden. z. B. tutorials/intermediate/constrainedlayout_guide.pyzeigt ein paar statische Bilder an:

# .. image:: /_static/constrained_layout_1b.png
#    :align: center

Dateien können wörtlich übernommen werden. Beispielsweise LICENSEist die Datei in der Lizenzvereinbarung enthalten

.. literalinclude:: ../../LICENSE/LICENSE

doc/galleryDas Beispielverzeichnis wird von sphinx-gallery kopiert , so dass Plots aus dem Beispielverzeichnis mit eingebunden werden können

.. plot:: gallery/lines_bars_and_markers/simple_plot.py

Beachten Sie, dass auf das Python-Skript verwiesen wird, das den Plot generiert, und nicht auf einen erstellten Plot. Die Sphinx-Galerie wird die richtige Referenz bereitstellen, wenn die Dokumentation erstellt wird.

Docstrings schreiben #

Der Großteil der API-Dokumentation ist in Docstrings geschrieben. Dies sind Kommentarblöcke im Quellcode, die erklären, wie der Code funktioniert.

Notiz

Einige Teile der Dokumentation entsprechen noch nicht dem aktuellen Dokumentationsstil. Befolgen Sie im Zweifelsfall die hier angegebenen Regeln und nicht das, was Sie möglicherweise im Quellcode sehen. Pull-Requests zur Aktualisierung von Docstrings auf den aktuellen Stil sind sehr willkommen.

Alle neuen oder bearbeiteten Docstrings sollten dem numpydoc Docstring Guide entsprechen . Ein Großteil der oben besprochenen ReST- Syntax ( Schreiben von ReST-Seiten ) kann für Links und Verweise verwendet werden. Diese Docstrings füllen schließlich das doc/apiVerzeichnis und bilden die Referenzdokumentation für die Bibliothek.

Beispiel docstring #

Ein Beispiel-Docstring sieht so aus:

def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
           label='', **kwargs):
    """
    Plot horizontal lines at each *y* from *xmin* to *xmax*.

    Parameters
    ----------
    y : float or array-like
        y-indexes where to plot the lines.

    xmin, xmax : float or array-like
        Respective beginning and end of each line. If scalars are
        provided, all lines will have the same length.

    colors : list of colors, default: :rc:`lines.color`

    linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional

    label : str, default: ''

    Returns
    -------
    `~matplotlib.collections.LineCollection`

    Other Parameters
    ----------------
    data : indexable object, optional
        DATA_PARAMETER_PLACEHOLDER
    **kwargs :  `~matplotlib.collections.LineCollection` properties.

    See Also
    --------
    vlines : vertical lines
    axhline : horizontal line across the Axes
    """

Sehen Sie in der hlinesDokumentation nach, wie dies gerendert wird.

Die Sphinx - Website enthält auch zahlreiche Dokumentationen zum ReST-Markup und zur Arbeit mit Sphinx im Allgemeinen.

Formatierungskonventionen #

Die grundlegenden Docstring-Konventionen werden in der numpydoc Docstring-Anleitung und der Sphinx - Dokumentation behandelt. Einige Matplotlib-spezifische Formatierungskonventionen, die Sie beachten sollten:

Angebotspositionen #

Die Anführungszeichen für einzeilige Dokumentzeichenfolgen befinden sich in derselben Zeile (pydocstyle D200):

def get_linewidth(self):
    """Return the line width in points."""

Die Anführungszeichen für mehrzeilige Dokumentzeichenfolgen befinden sich in separaten Zeilen (pydocstyle D213):

def set_linestyle(self, ls):
"""
Set the linestyle of the line.

[...]
"""

Funktionsargumente #

Auf Funktionsargumente und Schlüsselwörter innerhalb von Dokumentzeichenfolgen sollte mithilfe der *emphasis*Rolle verwiesen werden. Dadurch bleibt die Dokumentation von Matplotlib mit der Dokumentation von Python konsistent:

If *linestyles* is *None*, the default is 'solid'.

Verwenden Sie nicht die oder die Rolle:`default role```literal``

Neither `argument` nor ``argument`` should be used.

Anführungszeichen für Zeichenfolgen #

Matplotlib hat keine Konvention, ob einfache oder doppelte Anführungszeichen verwendet werden sollen. Es gibt eine Mischung aus beidem im aktuellen Code.

Verwenden Sie einfache einfache oder doppelte Anführungszeichen, wenn Sie Zeichenfolgenwerte angeben, z

If 'tight', try to figure out the tight bbox of the figure.

No ``'extra'`` literal quotes.

Von der Verwendung zusätzlicher wörtlicher Anführungszeichen um den Text herum wird abgeraten. Während sie die gerenderten Dokumente leicht verbessern, sind sie umständlich einzutippen und in Klartextdokumenten schwer zu lesen.

Beschreibungen der Parametertypen #

Das Hauptziel von Parametertypbeschreibungen ist es, für Menschen lesbar und verständlich zu sein. Wenn die möglichen Typen zu komplex sind, verwenden Sie eine Vereinfachung für die Typbezeichnung und erläutern Sie den Typ im Text genauer.

Im Allgemeinen gelten die Konventionen des numpydoc Docstring-Leitfadens . Die folgenden Regeln erweitern sie dort, wo die numpydoc-Konventionen nicht spezifisch sind.

Verwenden Sie floatfür einen Typ, der eine beliebige Zahl sein kann.

Zur Beschreibung einer 2D-Position verwenden . Die Klammern sollten eingefügt werden, um die Tupelhaftigkeit deutlicher zu machen.(float, float)

Verwenden Sie array-likefür homogene numerische Sequenzen, die typischerweise ein numpy.array sein könnten. Die Dimensionalität kann mit 2D, 3D, angegeben werden n-dimensional. Wenn Sie Variablen benötigen, die die Größen der Dimensionen angeben, verwenden Sie Großbuchstaben in Klammern ( ). Wenn im Text auf sie verwiesen wird, sind sie leichter lesbar und es ist keine besondere Formatierung erforderlich. Verwenden Sie statt für Rückgabetypen, wenn das zurückgegebene Objekt tatsächlich ein numpy-Array ist.(M, N) array-likearrayarray-like

floatist der implizite Standard-dtype für Array-likes. Verwenden Sie für andere dtypes .array-like of int

Einige mögliche Verwendungen:

2D array-like
(N,) array-like
(M, N) array-like
(M, N, 3) array-like
array-like of int

Nichtnumerische homogene Sequenzen werden als Listen beschrieben, z. B.:

list of str
list of `.Artist`

Referenztypen #

Generell gelten die Regeln von refering-to-other-code . Genauer:

Verwenden Sie vollständige Referenzen `~matplotlib.colors.Normalize`mit einer Abkürzung Tilde in Parametertypen. Während der vollständige Name dem Leser von Klartext-Docstrings hilft, muss der HTML-Code nicht den vollständigen Namen anzeigen, da er darauf verweist. Daher sorgt die ~-Verkürzung für eine bessere Lesbarkeit.

Verwenden Sie verkürzte Links `.Normalize`im Text.

norm : `~matplotlib.colors.Normalize`, optional
     A `.Normalize` instance is used to scale luminance data to 0, 1.

Standardwerte #

Im Gegensatz zur numpydoc-Anleitung müssen Parameter nicht als optional markiert werden, wenn sie einen einfachen Standardwert haben:

  • verwenden, wenn möglich.{name} : {type}, default: {val}

  • Verwenden und beschreiben Sie die Vorgabe im Text, wenn sie nicht in der empfohlenen Weise ausreichend erklärt werden kann.{name} : {type}, optional

Der Standardwert sollte semantische Informationen bereitstellen, die auf einen menschlichen Leser ausgerichtet sind. In einfachen Fällen wird der Wert in der Funktionssignatur neu formuliert. Gegebenenfalls sind Einheiten hinzuzufügen.

Prefer:
    interval : int, default: 1000ms
over:
    interval : int, default: 1000

Wenn None nur als Sentinel-Wert für "Parameter nicht angegeben" verwendet wird, dokumentieren Sie dies nicht als Standard. Geben Sie je nach Kontext den tatsächlichen Standardwert an oder markieren Sie den Parameter als optional, wenn die Nichtangabe keine besondere Wirkung hat.

Prefer:
    dpi : float, default: :rc:`figure.dpi`
over:
    dpi : float, default: None

Prefer:
    textprops : dict, optional
        Dictionary of keyword parameters to be passed to the
        `~matplotlib.text.Text` instance contained inside TextArea.
over:
    textprops : dict, default: None
        Dictionary of keyword parameters to be passed to the
        `~matplotlib.text.Text` instance contained inside TextArea.

See alsoAbschnitte #

Sphinx verknüpft automatisch Codeelemente in den Definitionsblöcken von Abschnitten. Keine Notwendigkeit, dort Backticks zu verwenden:See also

See Also
--------
vlines : vertical lines
axhline : horizontal line across the Axes

Parameterlisten umbrechen #

Lange Parameterlisten sollten mit einer For-Fortsetzung umbrochen werden \und auf der neuen Zeile ohne Einzug beginnen (kein Einzug, da pydoc den Docstring analysiert und die Zeilenfortsetzung entfernt, so dass der Einzug zu viel Leerraum innerhalb der Zeile führen würde):

def add_axes(self, *args, **kwargs):
    """
    ...

    Parameters
    ----------
    projection : {'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \
'rectilinear'}, optional
        The projection type of the axes.

    ...
    """

Alternativ können Sie die gültigen Parameterwerte in einem eigenen Abschnitt des Dokumentstrings beschreiben.

rcParams #

Auf rcParams kann mit der benutzerdefinierten :rc:Rolle referenziert werden: :rc:`foo`yields , die ein Link zur Dateibeschreibung ist.rcParams["foo"] = 'default'matplotlibrc

Setter und Getter #

Künstlereigenschaften werden mithilfe von Setter- und Getter-Methoden implementiert (da Matplotlib älter als der Python- propertyDekorator ist). Per Konvention werden diese Setter und Getter als set_PROPERTYNAMEund bezeichnet get_PROPERTYNAME; Die Liste der so definierten Eigenschaften eines Künstlers und ihrer Werte kann durch die Funktionen setpund aufgelistet werden getp.

Der Parameterblock von Methoden zum Festlegen von Eigenschaften wird analysiert, um die akzeptierten Werte zu dokumentieren, z. B. die Dokumentzeichenfolge von Line2D.set_linestylebeginnt mit

def set_linestyle(self, ls):
    """
    Set the linestyle of the line.

    Parameters
    ----------
    ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
        etc.
    """

was in der Ausgabe von plt.setp(line)or zu folgender Zeile führt :plt.setp(line, "linestyle")

linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}

In einigen seltenen Fällen (hauptsächlich Setter, die sowohl ein einzelnes Tupel als auch ein entpacktes Tupel akzeptieren) können die akzeptierten Werte nicht auf diese Weise dokumentiert werden; in diesem Fall können sie als Block dokumentiert werden, z. B. für :.. ACCEPTS:axes.Axes.set_xlim

def set_xlim(self, ...):
    """
    Set the x-axis view limits.

    Parameters
    ----------
    left : float, optional
        The left xlim in data coordinates. Passing *None* leaves the
        limit unchanged.

        The left and right xlims may also be passed as the tuple
        (*left*, *right*) as the first positional argument (or as
        the *left* keyword argument).

        .. ACCEPTS: (bottom: float, top: float)

    right : float, optional
        etc.
    """

Beachten Sie, dass der Zeilenvorsprung ..den Block zu einem reST-Kommentar macht und ihn vor den gerenderten Dokumenten verbirgt... ACCEPTS:

Keyword-Argumente #

Notiz

Die Informationen in diesem Abschnitt werden vom Entwicklungsteam aktiv diskutiert, also verwenden Sie die Docstring-Interpolation nur, wenn es nötig ist. Dieser Abschnitt wurde vorerst belassen, da diese Interpolation Teil der bestehenden Dokumentation ist.

Da Matplotlib viel Pass-Through verwendet kwargs, zB in jeder Funktion, die eine Linie erzeugt ( plot, semilogx, semilogy, etc.), kann es für den neuen Benutzer schwierig sein zu wissen, welche kwargsunterstützt werden. Matplotlib verwendet ein Docstring-Interpolationsschema, um die Dokumentation jeder Funktion zu unterstützen, die eine **kwargs. Die Anforderungen sind:

  1. Ein einziger Konfigurationspunkt, sodass Änderungen an den Eigenschaften nicht mehrere Docstring-Bearbeitungen erfordern.

  2. so automatisiert wie möglich, sodass die Dokumente automatisch aktualisiert werden, wenn sich die Eigenschaften ändern.

Der @_docstring.interpdDekorateur setzt dies um. Jede Funktion, die Line2DPass-Through akzeptiert kwargs, z. B. , matplotlib.axes.Axes.plotkann eine Zusammenfassung der Line2DEigenschaften wie folgt auflisten:

# in axes.py
@_docstring.interpd
def plot(self, *args, **kwargs):
    """
    Some stuff omitted

    Other Parameters
    ----------------
    scalex, scaley : bool, default: True
        These parameters determine if the view limits are adapted to the
        data limits. The values are passed on to `autoscale_view`.

    **kwargs : `.Line2D` properties, optional
        *kwargs* are used to specify properties like a line label (for
        auto legends), linewidth, antialiasing, marker face color.
        Example::

        >>> plot([1, 2, 3], [1, 2, 3], 'go-', label='line 1', linewidth=2)
        >>> plot([1, 2, 3], [1, 4, 9], 'rs', label='line 2')

        If you specify multiple lines with one plot call, the kwargs apply
        to all those lines. In case the label object is iterable, each
        element is used as labels for each set of data.

        Here is a list of available `.Line2D` properties:

        %(Line2D:kwdoc)s
    """

Die %(Line2D:kwdoc)Syntax lässt interpdeine ArtistUnterklasse mit dem Namen suchen und diese Klasse Line2Daufrufen . Untersucht die Unterklasse und fasst ihre Eigenschaften als Teilzeichenfolge zusammen, die in die Dokumentzeichenfolge interpoliert wird.artist.kwdocartist.kwdoc

Beachten Sie, dass dieses Schema nicht zum Dekorieren eines Künstlers funktioniert __init__, da die Unterklasse und ihre Eigenschaften zu diesem Zeitpunkt noch nicht definiert sind. Stattdessen @_docstring.interpdkann verwendet werden, um die Klasse selbst zu dekorieren – an diesem Punkt kwdockönnen die Eigenschaften aufgelistet und in __init__.__doc__.

Docstrings erben #

Wenn eine Unterklasse eine Methode überschreibt, aber die Semantik nicht ändert, können wir den übergeordneten Docstring für die Methode der untergeordneten Klasse wiederverwenden. Python tut dies automatisch, wenn die Methode der Unterklasse keinen Docstring hat.

Verwenden Sie einen einfachen Kommentar , um die Absicht anzugeben, den übergeordneten Dokumentstring wiederzuverwenden. Auf diese Weise erstellen wir in Zukunft nicht versehentlich einen Docstring:# docstring inherited

class A:
    def foo():
        """The parent docstring."""
        pass

class B(A):
    def foo():
        # docstring inherited
        pass

Zahlen hinzufügen #

Wie oben (siehe Einbinden von Abbildungen und Dateien ) kann auf Abbildungen in der Beispielgalerie mit einer Direktive verwiesen werden , die auf das Python-Skript verweist, das die Abbildung erstellt hat. Zum Beispiel verweist der Docstring auf die Datei :.. plot::legendexamples/text_labels_and_annotations/legend.py

"""
...

Examples
--------

.. plot:: gallery/text_labels_and_annotations/legend.py
"""

Beachten Sie, dass examples/text_labels_and_annotations/legend.pyzugeordnet wurde gallery/text_labels_and_annotations/legend.py, eine Umleitung, die möglicherweise bei einer zukünftigen Neuorganisation der Dokumente behoben wird.

Plots können auch direkt in Docstrings platziert werden. Details sind in matplotlib.sphinxext.plot_directive . Ein kurzes Beispiel ist:

"""
...

Examples
--------

.. plot::
   import matplotlib.image as mpimg
   img = mpimg.imread('_static/stinkbug.png')
   imgplot = plt.imshow(img)
"""

Ein Vorteil dieses Stils gegenüber dem Verweis auf ein Beispielskript besteht darin, dass der Code auch in interaktiven Docstrings angezeigt wird.

Schreibbeispiele und Tutorials #

Beispiele und Tutorials sind Python-Skripte, die von Sphinx Gallery ausgeführt werden, um eine Bildergalerie in den Verzeichnissen /doc/galleryund zu erstellen. /doc/tutorialsUm ein Beispiel von der Generierung eines Plots auszuschließen, fügen Sie irgendwo im Dateinamen "sgskip" ein.

Das Format dieser Dateien ist relativ einfach. Korrekt formatierte Kommentarblöcke werden als ReST- Text behandelt, der Code wird angezeigt und Abbildungen werden in die erstellte Seite eingefügt.

Zum Beispiel wird das Beispiel Simple Plot- Beispiel aus generiert /examples/lines_bars_and_markers/simple_plot.py, das wie folgt aussieht:

"""
===========
Simple Plot
===========

Create a simple plot.
"""
import matplotlib.pyplot as plt
import numpy as np

# Data for plotting
t = np.arange(0.0, 2.0, 0.01)
s = 1 + np.sin(2 * np.pi * t)

# Note that using plt.subplots below is equivalent to using
# fig = plt.figure and then ax = fig.add_subplot(111)
fig, ax = plt.subplots()
ax.plot(t, s)

ax.set(xlabel='time (s)', ylabel='voltage (mV)',
       title='About as simple as it gets, folks')
ax.grid()
plt.show()

Der erste Kommentarblock wird als ReST- Text behandelt. Die anderen Kommentarblöcke werden als Kommentare in Simple Plot gerendert .

Tutorials werden mit genau demselben Mechanismus erstellt, außer dass sie länger sind und normalerweise mehr als einen Kommentarblock haben ( z. B. Kurzanleitung ). Der erste Kommentarblock kann derselbe wie im obigen Beispiel sein. Nachfolgende Blöcke von ReST-Text werden durch eine Reihe von ###Zeichen getrennt:

"""
===========
Simple Plot
===========

Create a simple plot.
"""
...
ax.grid()
plt.show()

##########################################################################
# Second plot
# ===========
#
# This is a second plot that is very nice

fig, ax = plt.subplots()
ax.plot(np.sin(range(50)))

Auf diese Weise werden Texte, Codes und Zahlen im "Notebook"-Stil ausgegeben.

Sonstiges #

Umzugsdokumentation #

Manchmal ist es wünschenswert, Dokumentation zu verschieben oder zu konsolidieren. Ohne Aktion führt dies dazu, dass Links entweder tot sind (404) oder auf alte Versionen der Dokumentation verweisen. Vorzugsweise wird die alte Seite durch eine HTML-Aktualisierung ersetzt, die den Betrachter sofort auf die neue Seite umleitet. Also bewegen wir uns zum Beispiel /doc/topic/old_info.rstnach /doc/topic/new_info.rst. Wir entfernen /doc/topic/old_info.rstund /doc/topic/new_info.rstfügen eine redirect-fromAnweisung ein, die Sphinx anweist, die alte Datei mit der darin enthaltenen HTML-Aktualisierung/Umleitung weiterhin zu erstellen (wahrscheinlich am Anfang der Datei, um sie sichtbar zu machen).

.. redirect-from:: /topic/old_info

In den erstellten Dokumenten ergibt dies eine HTML-Datei /build/html/topic/old_info.htmlmit einer Aktualisierung auf new_info.html. Wenn sich die beiden Dateien in unterschiedlichen Unterverzeichnissen befinden:

.. redirect-from:: /old_topic/old_info2

ergibt eine HTML-Datei /build/html/old_topic/old_info2.html, die eine (relative) Aktualisierung zu ../topic/new_info.html.

Verwenden Sie für diese Anweisung den vollständigen Pfad relativ zum Dokumentstammverzeichnis unter https://matplotlib.org/stable/. So /old_topic/old_info2würde es von Benutzern unter gefunden werden http://matplotlib.org/stable/old_topic/old_info2. Verwenden Sie aus Gründen der Übersichtlichkeit keine relativen Links.

Animationen hinzufügen #

Animationen werden automatisch von der Sphinx-Galerie geschabt. Wenn dies nicht erwünscht ist, gibt es auch ein Matplotlib-Google/Gmail-Konto mit Benutzernamen mplgithub , das zum Einrichten des Github-Kontos verwendet wurde, aber für andere Zwecke verwendet werden kann, z. B. zum Hosten von Google-Dokumenten oder Youtube-Videos. Sie können eine Matplotlib-Animation in die Dokumentation einbetten, indem Sie zuerst die Animation als Film mit speichern matplotlib.animation.Animation.save()und dann auf den Youtube-Kanal von Matplotlib hochladen und die von YouTube bereitgestellte Einbettungszeichenfolge einfügen:

.. raw:: html

   <iframe width="420" height="315"
     src="https://www.youtube.com/embed/32cjc6V0OZY"
     frameborder="0" allowfullscreen>
   </iframe>

Ein Beispielspeicherbefehl zum Generieren eines Films sieht folgendermaßen aus

ani = animation.FuncAnimation(fig, animate, np.arange(1, len(y)),
    interval=25, blit=True, init_func=init)

ani.save('double_pendulum.mp4', fps=15)

Wenden Sie sich an Michael Droettboom, um das Anmeldepasswort zu erhalten, um YouTube-Videos von Google Docs in das mplgithub-Konto hochzuladen.

Vererbungsdiagramme erzeugen #

Klassenvererbungsdiagramme können mit der Sphinx -Inheritance-Diagram- Direktive generiert werden.

Beispiel:

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
   :parts: 2
Vererbungsdiagramm von matplotlib.patches, matplotlib.lines, matplotlib.text