Guida allo stile della documentazione #

Questa guida contiene le migliori pratiche per la lingua e la formattazione della documentazione di Matplotlib.

Guarda anche

Per ulteriori informazioni sul contributo, vedere la sezione Scrittura della documentazione .

Lingua espositiva #

Per la scrittura esplicativa, le seguenti linee guida sono per un uso del linguaggio chiaro e conciso.

Terminologia #

Esistono diversi termini chiave in Matplotlib che sono standard per l'affidabilità e la coerenza nella documentazione. Non sono intercambiabili.

Termine

Descrizione

Corretta

Errato

Figure

Spazio di lavoro Matplotlib per la programmazione.

  • Per gli oggetti Matplotlib : Figura, "La figura è lo spazio di lavoro per l'oggetto visivo.

  • Facendo riferimento alla classe : Figure, "I metodi all'interno di Figure forniscono le immagini."

  • Linguaggio generale : figura, "Michelle Kwan è una famosa pattinatrice artistica".

  • "La figura è lo spazio di lavoro per le immagini."

  • "I metodi nella figura forniscono le immagini."

  • "Il Figure Four leglock è una mossa di wrestling."

Axes

Sottotrame all'interno della figura. Contiene elementi di trama ed è responsabile della stampa e della configurazione di dettagli aggiuntivi.

  • Per gli oggetti Matplotlib : Axes, "An Axes è una sottotrama all'interno della figura".

  • Riferendosi alla classe : Axes, "Ciascuno Axesè specifico di una Figura."

  • Linguaggio generale : asce, "Sia i taglialegna che i boscaioli usano le asce per tagliare la legna". O "Non ci sono nomi standard per le coordinate nei tre assi." (plurale di asse)

  • "I metodi degli assi trasformano i dati."

  • "Ognuno Axesè specifico di una Figura."

  • "I musicisti sul palco chiamano le loro chitarre Axes."

  • "Il punto in cui gli assi si incontrano è l'origine del sistema di coordinate."

Artist

Ampia varietà di oggetti Matplotlib che visualizzano elementi visivi.

  • Per gli oggetti Matplotlib : Artist, "Gli artisti visualizzano elementi visivi e sono gli elementi visibili durante il rendering di una figura".

  • Facendo riferimento a class : Artist, "Ciascuno Artist ha i rispettivi metodi e funzioni."

  • Linguaggio generico : artista, "L'artista nel museo è francese".

  • "Configura l'artista legenda con il rispettivo metodo."

  • "C'è un'immagine Artist per quell'immagine nel grafico."

  • "Alcuni artisti sono diventati famosi solo per caso."

Axis

Oggetto unidimensionale leggibile dall'uomo di segni di riferimento contenenti segni di spunta, etichette di segno di spunta, dorsi e bordi.

  • Per gli oggetti Matplotlib : Axis, "L'asse per il grafico a barre è un artista separato". (plurale, oggetti Axis)

  • Facendo riferimento a class : Axis, " Axis Contiene i rispettivi oggetti XAxis e YAxis."

  • Linguaggio generale : axis, "La rotazione attorno ad un asse fisso è un caso speciale di moto rotatorio."

  • "Traccia il grafico sull'asse."

  • "Ogni asse prende solitamente il nome dalla coordinata che viene misurata lungo di esso."

  • "In alcuni contesti di computer grafica, l'ordinata Axispuò essere orientata verso il basso."

Programmazione esplicita orientata agli oggetti (OOP)

Approccio esplicito alla programmazione in Matplotlib.

  • Esplicito

  • esplicito

  • OOP

  • orientato agli oggetti

  • Stile OO

Implicito, pyplot

Approccio implicito alla programmazione in Matplotlib con pyplotmodulo.

  • Implicito

  • implicito

  • pyplot

  • come MATLAB

  • Pyplot

  • interfaccia pyplot

Grammatica #

Oggetto n.

Usa frasi imperative in seconda persona per istruzioni dirette che specificano un'azione. I pronomi in seconda persona sono per contesti individuali specifici e riferimenti possessivi.

Corretta

Errato

Installa Matplotlib dalla directory di origine utilizzando il pip programma di installazione di Python. A seconda del sistema operativo in uso, potrebbe essere necessario ulteriore supporto.

Puoi installare Matplotlib dalla directory di origine. Puoi trovare ulteriore supporto se riscontri problemi con l'installazione.

# teso

Usa il present simple per le spiegazioni. Evita il futuro e altri verbi modali o ausiliari quando possibile.

Corretta

Errato

Le idee fondamentali alla base di Matplotlib per la visualizzazione implicano l'acquisizione di dati e la loro trasformazione attraverso funzioni e metodi.

Matplotlib prenderà i dati e li trasformerà attraverso funzioni e metodi. Possono generare molti tipi di immagini. Questi saranno i fondamenti per l'utilizzo di Matplotlib.

Voce #

Scrivi in ​​frasi attive. La voce passiva è la migliore per situazioni o condizioni relative a messaggi di avviso.

Corretta

Errato

La funzione plotgenera il grafico.

Il grafico è generato dalla plotfunzione.

Un messaggio di errore viene restituito dalla funzione se non ci sono argomenti.

Verrà visualizzato un messaggio di errore dalla funzione se non ci sono argomenti.

Struttura della frase #

Scrivi con frasi brevi usando regolarmente l'ordine Soggetto-Verbo-Oggetto. Limita le congiunzioni coordinative nelle frasi. Evita i riferimenti pronome e le frasi congiuntive subordinate.

Corretta

Errato

Il pyplotmodulo in Matplotlib è una raccolta di funzioni. Queste funzioni creano, gestiscono e manipolano la figura corrente e l'area del tracciato.

Il pyplotmodulo in Matplotlib è una raccolta di funzioni che creano, gestiscono e manipolano la figura corrente e l'area di tracciamento.

La plotfunzione traccia i dati sui rispettivi assi. Gli Assi corrispondono alla rispettiva Figura.

La plotfunzione traccia i dati all'interno dei rispettivi assi per la rispettiva figura.

L'approccio implicito è una comoda scorciatoia per generare grafici semplici.

Gli utenti che desiderano disporre di comode scorciatoie per la generazione di grafici utilizzano l'approccio implicito.

Formattazione #

Le seguenti linee guida specificano come incorporare il codice e utilizzare la formattazione appropriata per la documentazione di Matplotlib.

Codice #

Matplotlib è una libreria Python e segue gli stessi standard per la documentazione.

Commenti #

Esempi di codice Python hanno commenti prima o sulla stessa riga.

Corretta

Errato

 
# Data
years = [2006, 2007, 2008]

years = [2006, 2007, 2008]
# Data

years = [2006, 2007, 2008]  # Data

Uscite #

Quando si generano oggetti visivi con Matplotlib utilizzando .pyi file negli esempi, visualizzare l'oggetto visivo con matplotlib.pyplot.showper visualizzare l'oggetto visivo. Mantieni la documentazione libera dalle righe di output di Python.

Corretta

Errato

 
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])

testo ristrutturato #

Matplotlib utilizza reStructuredText Markup per la documentazione. Sphinx aiuta a trasformare questi documenti in formati appropriati per l'accessibilità e la visibilità.

Liste #

Gli elenchi puntati sono per gli elementi che non richiedono una sequenza. Gli elenchi numerati servono esclusivamente per eseguire azioni in un determinato ordine.

Corretta

Errato

L'esempio utilizza tre grafici.

L'esempio utilizza tre grafici.

  • Sbarra

  • Linea

  • Torta

  1. Sbarra

  2. Linea

  3. Torta

Questi quattro passaggi aiutano a iniziare a utilizzare Matplotlib.

I passaggi seguenti sono importanti per iniziare a utilizzare Matplotlib.

  1. Importa la libreria Matplotlib.

  2. Importa i moduli necessari.

  3. Impostare e assegnare i dati su cui lavorare.

  4. Trasforma i dati con metodi e funzioni.

  • Importa la libreria Matplotlib.

  • Importa i moduli necessari.

  • Impostare e assegnare i dati su cui lavorare.

  • Trasforma i dati con metodi e funzioni.

Tabelle #

Utilizzare le tabelle ASCII con gli standard reStructuredText nell'organizzazione dei contenuti. Le tabelle Markdown e la direttiva csv-table non sono accettate.

Corretta

Errato

Corretta

Errato

OK

Non bene

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

Risorse aggiuntive #

Questa guida di stile non è uno standard completo. Per un riferimento più approfondito su come contribuire alla documentazione, vedere i collegamenti sottostanti. Queste risorse contengono best practice comuni per la scrittura della documentazione.