MEP12: Galerie und Beispiele verbessern #

Status #

Fortschritt

Anfängliche Änderungen in 1.3 hinzugefügt. Der Umbau der Galerie ist im Gange. 29. September 2015 – Der letzte Importort wurde pylab_examplesauf pylabdie Verwendung von matplotlib.pyplotund umgestellt numpy.

Branches und Pull-Requests #

Nr. 1623, Nr. 1924, Nr. 2181

PR #2474 zeigt ein einzelnes Beispiel, das bereinigt und in den entsprechenden Abschnitt verschoben wird.

Zusammenfassung #

Die Reorganisation der Matplotlib-Plot-Galerie würde die Navigation in der Galerie erheblich vereinfachen. Darüber hinaus sollten die Beispiele bereinigt und vereinfacht werden, um sie klarer zu machen.

Detaillierte Beschreibung #

Die Matplotlib-Galerie wurde kürzlich eingerichtet, um Beispiele in Abschnitte aufzuteilen. Wie in diesem PR [ 1 ] besprochen , sind die aktuellen Beispielabschnitte ( api, pylab_examples) für Benutzer nicht besonders nützlich: Neue Abschnitte in der Galerie würden Benutzern helfen, relevante Beispiele zu finden.

Diese Abschnitte würden auch eine Bereinigung der Beispiele anleiten: Anfänglich würden alle aktuellen Beispiele bleiben und unter ihren aktuellen Verzeichnissen aufgelistet werden. Im Laufe der Zeit könnten diese Beispiele aufgeräumt und in einen der neuen Abschnitte verschoben werden.

Dieser Prozess ermöglicht Benutzern die einfache Identifizierung von Beispielen, die bereinigt werden müssen; dh alles in den apiund pylab_examples Verzeichnissen.

Implementierung #

Erstellen Sie neue Galerieabschnitte. [Fertig]
Beispiele aufräumen und in die neuen Galeriebereiche verschieben (im Laufe vieler PRs und mit Hilfe vieler Benutzer/Entwickler). [Im Gange]

Galerieabschnitte #

Die Benennung von Abschnitten ist entscheidend und wird die Aufräumarbeiten leiten. Die aktuellen Abschnitte sind:

Linien, Balken und Markierungen (mehr oder weniger 1D-Daten)
Formen und Kollektionen
Statistische Diagramme
Bilder, Konturen und Felder
Torten- und Polardiagramme: Runde Dinge
Farbe
Text, Beschriftungen und Anmerkungen
Zecken und Stacheln
Nebenhandlungen, Achsen und Zahlen
Spezialplots (z. B. Sankey, Radar, Tornado)
Showcase (Plots mit Optimierungen, um sie in Veröffentlichungsqualität zu bringen)
separate Abschnitte für Toolboxen (bereits vorhanden: 'mplot3d', 'axes_grid', 'units', 'widgets')

Diese Namen stehen sicherlich zur Debatte. Wenn diese Abschnitte wachsen, sollten wir sie neu bewerten und nach Bedarf aufteilen.

Richtlinien zur Bereinigung #

Die aktuellen Beispiele in den Abschnitten apiund pylab_examplesder Galerie würden in diesen Verzeichnissen verbleiben, bis sie bereinigt werden. Nach der Säuberung würden sie in einen der oben beschriebenen neuen Galerieabschnitte verlegt. "Aufräumen" sollte beinhalten:

sphinx-gallery docstrings : ein Titel und eine Beschreibung des Beispiels, die wie folgt formatiert sind, oben im Beispiel:

"""
===============================
Colormaps alter your perception
===============================

Here I plot the function

.. math:: f(x, y) = \sin(x) + \cos(y)

with different colormaps. Look at how colormaps alter your perception!
"""

PEP8 -Bereinigungen (Running flake8 oder ein ähnlicher Checker wird dringend empfohlen)
Auskommentierter Code sollte entfernt werden.
Ersetzen Sie die Verwendungen der pylabSchnittstelle durch pyplot(+ numpyusw.). Siehe c25ef1e
Shebang-Linie entfernen, zB:

#!/usr/bin/env python
Verwenden Sie konsistente Importe. Im Speziellen:

importiere numpy als np

matplotlib.pyplot als plt importieren

Vermeiden Sie den Import bestimmter Funktionen aus diesen Modulen (z. B. )from numpy import sin
Jedes Beispiel sollte sich auf ein bestimmtes Merkmal konzentrieren (mit Ausnahme von showcaseBeispielen, die "ausgefeiltere" Diagramme zeigen). Optimierungen, die nichts mit dieser Funktion zu tun haben, sollten entfernt werden. Siehe f7b2217 , e57b5fc und 1458aa8

Die Verwendung von pylabsollte auf einer speziellen Hilfeseite anstelle der Galeriebeispiele demonstriert/diskutiert werden.

Hinweis: Wenn Sie ein vorhandenes Beispiel verschieben, sollten Sie nach Verweisen auf dieses Beispiel suchen. Beispielsweise kann die API-Dokumentation für axes.pyund pyplot.pydiese Beispiele verwenden, um Diagramme zu generieren. Verwenden Sie Ihr bevorzugtes Suchwerkzeug (z. B. grep, ack, grin , pss ), um das matplotlib-Paket zu durchsuchen. Siehe 2dc9a46 und aa6b410

Zusätzliche Vorschläge #

Stellen Sie Links (in beide Richtungen) zwischen Beispielen und API-Dokumenten für die verwendeten Methoden/Objekte bereit. (Ausgabe #2222 )
Verwenden Sie plt.subplots(beachten Sie das abschließende "s") gegenüber plt.subplot.
Benennen Sie das Beispiel um, um seinen Zweck zu verdeutlichen. Beispielsweise imshowkönnte die einfachste Demo von sein imshow_demo.py, und eine, die verschiedene Interpolationseinstellungen demonstriert, wäre imshow_demo_interpolation.py( not imshow_demo2.py ).
Teilen Sie Beispiele auf, die versuchen, zu viel zu tun. Siehe 5099675 und fc2ab07
Löschen Sie Beispiele, die nichts Neues zeigen.
Einige Beispiele üben esoterische Funktionen für Unit-Tests aus. Diese Anpassungen sollten aus der Galerie in ein Beispiel im unitVerzeichnis verschoben werden, das sich im Stammverzeichnis des Pakets befindet.
Fügen Sie Handlungstitel hinzu, um die Absicht des Beispiels zu verdeutlichen. Siehe bd2b13c

Abwärtskompatibilität #

Die Website für jede Matplotlib-Version ist leicht zugänglich, sodass Benutzer, die auf alte Beispiele verweisen möchten, dies weiterhin tun können.

Alternativen #

Stichworte #

Tagging-Beispiele helfen Benutzern auch beim Durchsuchen der Beispielgalerie. Obwohl Tags ein großer Gewinn für Benutzer mit bestimmten Zielen wären, bleibt die Plot-Galerie der Einstiegspunkt zu diesen Beispielen, und Abschnitte könnten den Benutzern wirklich helfen, sich in der Galerie zurechtzufinden. Daher sind Tags komplementär zu dieser Reorganisation.