Dokumentations-Styleguide #

Dieses Handbuch enthält Best Practices für die Sprache und Formatierung der Matplotlib-Dokumentation.

Siehe auch

Weitere Informationen zum Beitragen finden Sie im Abschnitt Dokumentation schreiben .

Ausstellungssprache #

Für erklärendes Schreiben gelten die folgenden Richtlinien für eine klare und prägnante Sprachverwendung.

Terminologie #

Es gibt mehrere Schlüsselbegriffe in Matplotlib, die Standards für Zuverlässigkeit und Konsistenz in der Dokumentation sind. Sie sind nicht austauschbar.

Begriff	Beschreibung	Richtig	Falsch
`Figure`	Matplotlib-Arbeitsbereich zum Programmieren.	Für Matplotlib-Objekte : Figure, „The Figure is the working space for the visual. Bezugnehmend auf class : `Figure`, "Methoden innerhalb der `Figure` bieten die Visuals." Allgemeine Sprache : Figur, "Michelle Kwan ist eine berühmte Eiskunstläuferin."	"Die Figur ist der Arbeitsraum für Visuals." "Methoden in der Abbildung liefern die Visualisierungen." "Der `Figure` Vierbeiner ist ein Wrestling-Move."
`Axes`	Nebenhandlungen innerhalb von Abbildung. Enthält Plotelemente und ist für das Plotten und Konfigurieren zusätzlicher Details verantwortlich.	Für Matplotlib-Objekte : Axes: „Eine Axes ist eine Nebenhandlung innerhalb der Figur.“ In Bezug auf die Klasse : `Axes`"Jede `Axes`ist spezifisch für eine Figur." Allgemeine Sprache : Äxte, "Sowohl Holzfäller als auch Holzfäller verwenden Äxte, um Holz zu hacken." ODER "Es gibt keine Standardnamen für die Koordinaten in den drei Achsen." (Plural von Achse)	"Die Achsenmethoden transformieren die Daten." "Jeder `Axes`ist spezifisch für eine Figur." "Die Musiker auf der Bühne nennen ihre Gitarren Axes." "Der Punkt, an dem sich die Achsen treffen, ist der Ursprung des Koordinatensystems."
`Artist`	Große Auswahl an Matplotlib-Objekten, die Visuals anzeigen.	Für Matplotlib-Objekte : Artist: „Künstler zeigen visuelle Elemente an und sind die sichtbaren Elemente beim Rendern einer Figur.“ Bezugnehmend auf die Klasse : `Artist`"Jede `Artist` hat entsprechende Methoden und Funktionen." Allgemeine Sprache : Künstler, "Der Künstler im Museum kommt aus Frankreich."	"Konfiguriere den Legendenkünstler mit seiner jeweiligen Methode." "Es gibt ein `Artist` für dieses Bild in der Grafik." "Manche Künstler wurden nur durch Zufall berühmt."
`Axis`	Für den Menschen lesbares eindimensionales Objekt aus Referenzmarkierungen, das Markierungen, Markierungen, Stacheln und Kanten enthält.	Für Matplotlib-Objekte : Achse, "Die Achse für das Balkendiagramm ist ein separater Künstler." (Plural, Achsenobjekte) Bezugnehmend auf class : `Axis`, "The `Axis` enthält entsprechende XAxis- und YAxis-Objekte." Allgemeine Sprache : Achse, "Rotation um eine feste Achse ist ein Sonderfall der Rotationsbewegung."	"Zeichnen Sie den Graphen auf die Achse." "Jede Achse wird normalerweise nach der Koordinate benannt, die entlang ihr gemessen wird." "In einigen Computergrafikkontexten kann die Ordinate `Axis`nach unten orientiert sein."
Explizite, objektorientierte Programmierung (OOP)	Explizite Herangehensweise an die Programmierung in Matplotlib.	Explizit explizit Hoppla	objektorientierter OO-Stil
Implizit, `pyplot`	Impliziter Ansatz der Programmierung in Matplotlib mit `pyplot`Modul.	Implizit implizit `pyplot`	MATLAB-ähnlich Pyplot pyplot-Schnittstelle

Grammatik #

Betreff #

Verwenden Sie Imperativsätze der zweiten Person für gezielte Anweisungen, die eine Handlung angeben. Pronomen der zweiten Person sind für personenspezifische Kontexte und Possessivbezüge.

Richtig	Falsch
Installieren Sie Matplotlib aus dem Quellverzeichnis mit dem Python- `pip` Installationsprogramm. Abhängig von Ihrem Betriebssystem benötigen Sie möglicherweise zusätzliche Unterstützung.	Sie können Matplotlib aus dem Quellverzeichnis installieren. Hier finden Sie zusätzliche Unterstützung, wenn Sie Probleme mit Ihrer Installation haben.

Anspannung #

Verwenden Sie für Erklärungen das Präsens Simple. Vermeiden Sie nach Möglichkeit das Futur und andere Modal- oder Hilfsverben.

Richtig	Falsch
Die grundlegenden Ideen hinter Matplotlib für die Visualisierung bestehen darin, Daten zu nehmen und sie durch Funktionen und Methoden umzuwandeln.	Matplotlib nimmt Daten und transformiert sie durch Funktionen und Methoden. Sie können viele Arten von Visuals erzeugen. Dies sind die Grundlagen für die Verwendung von Matplotlib.

Stimme #

Schreiben Sie in Aktivsätzen. Passive Sprache eignet sich am besten für Situationen oder Bedingungen im Zusammenhang mit Warnhinweisen.

Richtig	Falsch
Die Funktion `plot`erzeugt den Graphen.	Der Graph wird von der `plot`Funktion generiert.
Wenn keine Argumente vorhanden sind, wird von der Funktion eine Fehlermeldung zurückgegeben.	Sie sehen eine Fehlermeldung von der Funktion, wenn keine Argumente vorhanden sind.

Satzstruktur #

Schreiben Sie regelmäßig in kurzen Sätzen in der Reihenfolge Subjekt-Verb-Objekt. Beschränke koordinierende Konjunktionen in Sätzen. Vermeiden Sie Pronomenbezüge und unterordnende Konjunktivphrasen.

Richtig	Falsch
Das `pyplot`Modul in Matplotlib ist eine Sammlung von Funktionen. Diese Funktionen erstellen, verwalten und manipulieren die aktuelle Figur und den Plotbereich.	Das `pyplot`Modul in Matplotlib ist eine Sammlung von Funktionen, die die aktuelle Figur und den Plotbereich erstellen, verwalten und manipulieren.
Die `plot`Funktion zeichnet Daten auf den jeweiligen Achsen auf. Die Achsen entsprechen der jeweiligen Figur.	Die `plot`Funktion zeichnet Daten innerhalb ihrer jeweiligen Achsen für ihre jeweilige Figur.
Der implizite Ansatz ist eine bequeme Abkürzung zum Generieren einfacher Diagramme.	Benutzer, die praktische Abkürzungen zum Generieren von Diagrammen haben möchten, verwenden den impliziten Ansatz.

Formatierung #

Die folgenden Richtlinien geben an, wie Code integriert und die entsprechende Formatierung für die Matplotlib-Dokumentation verwendet wird.

Code #

Matplotlib ist eine Python-Bibliothek und folgt den gleichen Standards für die Dokumentation.

Kommentare #

Beispiele für Python-Code haben Kommentare vor oder in derselben Zeile.

Richtig	Falsch
# Data years = [2006, 2007, 2008]	years = [2006, 2007, 2008] # Data
years = [2006, 2007, 2008] # Data	years = [2006, 2007, 2008] # Data

Ausgänge #

Wenn Sie Visuals mit Matplotlib unter Verwendung von .pyDateien in Beispielen generieren, zeigen Sie das Visual mit matplotlib.pyplot.showan, um das Visual anzuzeigen. Halten Sie die Dokumentation frei von Python-Ausgabezeilen.

Richtig	Falsch
plt.plot([1, 2, 3], [1, 2, 3]) plt.show()	plt.plot([1, 2, 3], [1, 2, 3])
fig, ax = plt.subplots() ax.plot([1, 2, 3], [1, 2, 3]) fig.show()	fig, ax = plt.subplots() ax.plot([1, 2, 3], [1, 2, 3])

reStructuredText #

Matplotlib verwendet reStructuredText Markup für die Dokumentation. Sphinx hilft dabei, diese Dokumente in geeignete Formate für Zugänglichkeit und Sichtbarkeit umzuwandeln.

Listen #

Listen mit Aufzählungszeichen sind für Elemente, die keine Sequenzierung erfordern. Nummerierte Listen dienen ausschließlich dazu, Aktionen in einer bestimmten Reihenfolge auszuführen.

Richtig	Falsch
Das Beispiel verwendet drei Diagramme.	Das Beispiel verwendet drei Diagramme.
Bar Linie Kuchen	Bar Linie Kuchen
Diese vier Schritte helfen beim Einstieg in die Verwendung von Matplotlib.	Die folgenden Schritte sind wichtig, um mit der Verwendung von Matplotlib zu beginnen.
Importieren Sie die Matplotlib-Bibliothek. Importieren Sie die erforderlichen Module. Festlegen und Zuweisen von Daten, an denen gearbeitet werden soll. Transformieren Sie Daten mit Methoden und Funktionen.	Importieren Sie die Matplotlib-Bibliothek. Importieren Sie die erforderlichen Module. Festlegen und Zuweisen von Daten, an denen gearbeitet werden soll. Transformieren Sie Daten mit Methoden und Funktionen.

Tabellen #

Verwenden Sie ASCII-Tabellen mit reStructuredText-Standards zum Organisieren von Inhalten. Markdown-Tabellen und die csv-table-Direktive werden nicht akzeptiert.

Richtig

Falsch

Richtig	Falsch
OK	Nicht ok

| Correct | Incorrect |
| ------- | --------- |
| OK      | Not OK    |

+----------+----------+
| Correct  | Incorrect|
+==========+==========+
| OK       | Not OK   |
+----------+----------+

.. csv-table::
   :header: "correct", "incorrect"
   :widths: 10, 10

   "OK   ", "Not OK"

===========  ===========
  Correct     Incorrect
===========  ===========
OK           Not OK
===========  ===========

Zusätzliche Ressourcen #

Dieser Styleguide ist kein umfassender Standard. Eine ausführlichere Referenz dazu, wie Sie zur Dokumentation beitragen können, finden Sie unter den folgenden Links. Diese Ressourcen enthalten allgemeine Best Practices für das Schreiben von Dokumentation.