MEP12: Migliora la galleria e gli esempi #

Stato n.

Progresso

Modifiche iniziali aggiunte in 1.3. La conversione della galleria è in corso. 29 settembre 2015 - L'ultimo pylab_examplesdove pylabè importato è stato convertito in uso matplotlib.pyplote numpy.

Filiali e Pull request #

#1623, #1924, #2181

PR #2474 mostra un singolo esempio che viene ripulito e spostato nella sezione appropriata.

Estratto n.

La riorganizzazione della galleria di grafici matplotlib semplificherebbe notevolmente la navigazione della galleria. Inoltre, gli esempi dovrebbero essere ripuliti e semplificati per chiarezza.

Descrizione dettagliata #

La galleria matplotlib è stata recentemente creata per suddividere gli esempi in sezioni. Come discusso in quel PR [ 1 ] , le attuali sezioni di esempio ( api, pylab_examples) non sono particolarmente utili per gli utenti: nuove sezioni nella galleria aiuterebbero gli utenti a trovare esempi rilevanti.

Queste sezioni guiderebbero anche una pulizia degli esempi: inizialmente, tutti gli esempi correnti rimarrebbero e sarebbero elencati nelle loro attuali directory. Nel tempo, questi esempi potrebbero essere ripuliti e spostati in una delle nuove sezioni.

Questo processo consente agli utenti di identificare facilmente gli esempi che devono essere ripuliti; cioè qualsiasi cosa nelle directory apie pylab_examples .

Implementazione n.

Crea nuove sezioni della galleria. [Fatto]
Ripulisci gli esempi e spostali nelle nuove sezioni della galleria (nel corso di molte pubbliche relazioni e con l'aiuto di molti utenti/sviluppatori). [In corso]

Sezioni della galleria #

La denominazione delle sezioni è fondamentale e guiderà lo sforzo di pulizia. Le sezioni attuali sono:

Linee, barre e marcatori (dati più o meno 1D)
Forme e collezioni
Grafici statistici
Immagini, contorni e campi
Grafici a torta e polari: cose rotonde
Colore
Testo, etichette e annotazioni
Zecche e spine
Sottotrame, assi e figure
Trame speciali (p. es., sankey, radar, tornado)
Vetrina (trame con modifiche per renderle di qualità da pubblicazione)
sezioni separate per toolbox (già esistenti: 'mplot3d', 'axes_grid', 'units', 'widgets')

Questi nomi sono certamente in discussione. Man mano che queste sezioni crescono, dovremmo rivalutarle e suddividerle secondo necessità.

Linee guida per la pulizia #

Gli esempi correnti nelle sezioni apie pylab_examplesdella galleria rimarranno in quelle directory fino a quando non saranno ripuliti. Dopo la pulizia, sarebbero stati spostati in una delle nuove sezioni della galleria sopra descritte. La "pulizia" dovrebbe comportare:

sphinx-gallery docstrings : un titolo e una descrizione dell'esempio formattato come segue, nella parte superiore dell'esempio:

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

Pulizia PEP8 (si consiglia vivamente di eseguire flake8 o un controllore simile)
Il codice commentato deve essere rimosso.
Sostituire gli usi pylabdell'interfaccia con pyplot(+ numpy, ecc.). Vedi c25ef1e
Rimuovi la linea Shebang, ad esempio:

#!/usr/bin/env python
Utilizza importazioni coerenti. In particolare:

importa numpy come np

importa matplotlib.pyplot come plt

Evita di importare funzioni specifiche da questi moduli (es. )from numpy import sin
Ogni esempio dovrebbe concentrarsi su una caratteristica specifica (esclusi showcasegli esempi, che mostreranno trame più "raffinate"). Le modifiche non correlate a quella funzione dovrebbero essere rimosse. Vedere f7b2217 , e57b5fc e 1458aa8

L'uso di pylabdovrebbe essere dimostrato/discusso in una pagina di aiuto dedicata invece che negli esempi della galleria.

Nota: quando sposti un esempio esistente, dovresti cercare i riferimenti a quell'esempio. Ad esempio, la documentazione API per axes.pye pyplot.pypuò utilizzare questi esempi per generare grafici. Usa il tuo strumento di ricerca preferito (ad esempio, grep, ack, grin , pss ) per cercare nel pacchetto matplotlib. Vedi 2dc9a46 e aa6b410

Ulteriori suggerimenti #

Fornire collegamenti (in entrambe le direzioni) tra esempi e documenti API per i metodi/oggetti utilizzati. (numero #2222 )
Utilizzare plt.subplots(notare la "s" finale) al posto di plt.subplot.
Rinominare l'esempio per chiarirne lo scopo. Ad esempio, la demo più semplice di imshowpotrebbe essere imshow_demo.pye una che dimostri diverse impostazioni di interpolazione sarebbe imshow_demo_interpolation.py( not imshow_demo2.py ).
Suddividi gli esempi che cercano di fare troppo. Vedere 5099675 e fc2ab07
Elimina gli esempi che non mostrano nulla di nuovo.
Alcuni esempi esercitano caratteristiche esoteriche per i test unitari. Queste modifiche dovrebbero essere spostate fuori dalla galleria in un esempio nella unitdirectory che si trova nella directory principale del pacchetto.
Aggiungi i titoli della trama per chiarire l'intento dell'esempio. Vedi bd2b13c

Compatibilità con le versioni precedenti #

Il sito Web per ogni versione di Matplotlib è facilmente accessibile, quindi gli utenti che desiderano fare riferimento a vecchi esempi possono ancora farlo.

Alternative #

Tag #

Gli esempi di codifica aiuteranno anche gli utenti a cercare nella galleria di esempio. Sebbene i tag sarebbero una grande vittoria per gli utenti con obiettivi specifici, la galleria della trama rimarrà il punto di accesso a questi esempi e le sezioni potrebbero davvero aiutare gli utenti a navigare nella galleria. Pertanto, i tag sono complementari a questa riorganizzazione.