MEP12 : Améliorer la galerie et les exemples #

Statut #

Progrès

Changements initiaux ajoutés en 1.3. La reconversion de la galerie est en cours. 29 septembre 2015 - Le dernier pylab_examplesoù pylabest importé a été converti pour utiliser matplotlib.pyplotet numpy.

Branches et demandes d'extraction #

#1623, #1924, #2181

PR #2474 montre un seul exemple nettoyé et déplacé vers la section appropriée.

Résumé #

La réorganisation de la galerie de tracés matplotlib simplifierait grandement la navigation de la galerie. De plus, les exemples doivent être nettoyés et simplifiés pour plus de clarté.

Descriptif détaillé #

La galerie matplotlib a été récemment créée pour diviser les exemples en sections. Comme indiqué dans ce PR [ 1 ] , les sections d'exemples actuelles ( api, pylab_examples) ne sont pas très utiles aux utilisateurs : de nouvelles sections dans la galerie aideraient les utilisateurs à trouver des exemples pertinents.

Ces sections guideraient également un nettoyage des exemples : initialement, tous les exemples actuels resteraient et seraient répertoriés dans leurs répertoires actuels. Au fil du temps, ces exemples pourraient être nettoyés et déplacés dans l'une des nouvelles sections.

Ce processus permet aux utilisateurs d'identifier facilement les exemples qui doivent être nettoyés ; c'est-à-dire tout ce qui se trouve dans les répertoires apiet pylab_examples .

Mise en œuvre #

Créer de nouvelles sections de galerie. [Fait]
Nettoyez les exemples et déplacez-les vers les nouvelles sections de la galerie (au cours de nombreux PR et avec l'aide de nombreux utilisateurs/développeurs). [En cours]

Sections de la galerie #

La dénomination des sections est essentielle et guidera l'effort de nettoyage. Les rubriques actuelles sont :

Lignes, barres et marqueurs (données plus ou moins 1D)
Formes et collections
Graphiques statistiques
Images, contours et champs
Graphiques circulaires et graphiques polaires : arrondir les choses
Couleur
Texte, étiquettes et annotations
Tiques et épines
Sous-parcelles, axes et figures
Parcelles spécialisées (par exemple, sankey, radar, tornado)
Showcase (intrigues avec des ajustements pour les rendre de qualité publication)
sections séparées pour les boîtes à outils (existe déjà : 'mplot3d', 'axes_grid', 'units', 'widgets')

Ces noms sont certainement à débattre. Au fur et à mesure que ces sections grandissent, nous devrions les réévaluer et les diviser si nécessaire.

Consignes de nettoyage #

Les exemples actuels dans les sections apiet pylab_examplesde la galerie resteraient dans ces répertoires jusqu'à ce qu'ils soient nettoyés. Après le nettoyage, ils seraient déplacés vers l'une des nouvelles sections de la galerie décrites ci-dessus. Le "nettoyage" devrait impliquer :

sphinx-gallery docstrings : un titre et une description de l'exemple formaté comme suit, en haut de l'exemple :

"""
===============================
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!
"""

Nettoyages PEP8 (l'exécution de flake8 ou d'un vérificateur similaire est fortement recommandée)
Le code commenté doit être supprimé.
Remplacez les usages de l' pylabinterface par pyplot(+ numpy, etc.). Voir c25ef1e
Supprimer la ligne shebang, par exemple :

#!/usr/bin/envpython
Utilisez des importations cohérentes. En particulier:

importer numpy comme np

importer matplotlib.pyplot en tant que plt

Évitez d'importer des fonctions spécifiques de ces modules (par exemple )from numpy import sin
Chaque exemple doit se concentrer sur une fonctionnalité spécifique (à l'exception showcasedes exemples, qui montreront des tracés plus "finis"). Les ajustements sans rapport avec cette fonctionnalité doivent être supprimés. Voir f7b2217 , e57b5fc et 1458aa8

L'utilisation de pylabdoit être démontrée/discutée sur une page d'aide dédiée au lieu des exemples de la galerie.

Remarque : Lorsque vous déplacez un exemple existant, vous devez rechercher des références à cet exemple. Par exemple, la documentation de l'API pour axes.pyet pyplot.pypeut utiliser ces exemples pour générer des tracés. Utilisez votre outil de recherche préféré (par exemple, grep, ack, grin , pss ) pour rechercher le package matplotlib. Voir 2dc9a46 et aa6b410

Suggestions supplémentaires #

Fournissez des liens (dans les deux sens) entre les exemples et les documents de l'API pour les méthodes/objets utilisés. (numéro #2222 )
Utilisez plt.subplots(notez "s" à la fin) de préférence à plt.subplot.
Renommez l'exemple pour clarifier son objectif. Par exemple, la démonstration la plus basique de imshowpourrait être imshow_demo.py, et une démontrant différents paramètres d'interpolation serait imshow_demo_interpolation.py( not imshow_demo2.py ).
Séparez les exemples qui essaient d'en faire trop. Voir 5099675 et fc2ab07
Supprimez les exemples qui ne montrent rien de nouveau.
Certains exemples présentent des fonctionnalités ésotériques pour les tests unitaires. Ces ajustements doivent être déplacés hors de la galerie vers un exemple dans le unitrépertoire situé dans le répertoire racine du package.
Ajoutez des titres de tracé pour clarifier l'intention de l'exemple. Voir bd2b13c

Rétrocompatibilité #

Le site Web de chaque version de Matplotlib est facilement accessible, de sorte que les utilisateurs qui souhaitent se référer à d'anciens exemples peuvent toujours le faire.

Alternatives #

Balises #

Le marquage d'exemples aidera également les utilisateurs à effectuer des recherches dans la galerie d'exemples. Bien que les balises seraient une grande victoire pour les utilisateurs ayant des objectifs spécifiques, la galerie de tracés restera le point d'entrée de ces exemples, et les sections pourraient vraiment aider les utilisateurs à naviguer dans la galerie. Ainsi, les balises sont complémentaires à cette réorganisation.