Progetto Matplotlib

Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.

Riepilogo del progetto

Organizzazione open source:
Matplotlib
Technical Writer:
brunobeltran
Nome del progetto:
Migliorare la rilevabilità delle funzionalità standardizzando la documentazione dei tipi "impliciti"
Durata del progetto:
A lungo termine (5 mesi)

Project description

Motivazione

In passato, l'API di matplotlib si basava molto su stringhe come enumerazioni ""tipi impliciti"". Oltre a imitare l'API di Matlab, queste stringhe di parametri consentono all'utente di passare valori semanticamente complessi come argomenti alle funzioni matplotlib senza dover importare esplicitamente o anteporre un prefisso verboso a un valore enumerato effettivo solo per passare le opzioni di grafico di base (ad es. plt.plot(x, y, linestyle='solid') è più facile da digitare e meno ridondante di qualcosa come plt.plot(x, y, linestyle=mpl.LineStyle.solid)).

Da allora molti di questi tipi impliciti "stringa come enum" hanno sviluppato funzionalità più sofisticate. Ad esempio, linestyle ora può essere una stringa o una tupla a 2 tuple di sequenze, mentre un MarkerStyle può ora essere una stringa o un matplotlib.path.Path. Sebbene questo sia vero per molti tipi impliciti, MarkerStyle è l'unico (a mia conoscenza) che ha lo stato di aver subito l'upgrade a una classe Python adeguata.

Poiché questi tipi impliciti non sono classi a sé stanti, in passato Matplotlib ha dovuto implementare le proprie soluzioni per centralizzare la documentazione e la convalida di questi tipi impliciti (ad es. il pattern di interpolazione della docstring docstring.interpd.update e il pattern di convalida cbook._check_in_list, rispettivamente) anziché utilizzare le toolchain standard fornite dalle classi Python (ad es. le docstring e il pattern validate-at-__init__, rispettivamente).

Sebbene queste soluzioni abbiano funzionato bene per noi, la mancanza di una posizione esplicita per documentare ogni tipo implicito significa che la documentazione è spesso difficile da trovare, le tabelle di valori consentiti di grandi dimensioni vengono ripetute in tutta la documentazione e spesso un'affermazione esplicita dell'ambito di un tipo implicito è completamente assente dalla documentazione. Prendi ad esempio la documentazione di plt.plot: nelle ""Note"", una descrizione del metodo di stile della stringa di formato simile a Matlab menziona le opzioni linestyle, color e markers. Esistono molti più modi per passare questi tre valori di quanto non sia stato accennato, ma per molti utenti questa è l'unica fonte di informazioni sui valori possibili per queste opzioni finché non trovano uno dei tutorial pertinenti. Una tabella degli attributi Line2D è inclusa nel tentativo di mostrare al lettore le opzioni a sua disposizione per controllare la trama. Tuttavia, mentre la voce linestyle rimanda correttamente a Line2D.set_linestyle (sono necessari due clic) dove sono descritti i possibili input, le voci color e markers non lo fanno. color si collega semplicemente a Line2D.set_color, il che non offre alcuna idea sui tipi di input consentiti.

Si potrebbe sostenere che si tratta di un problema che può essere risolto semplicemente riordinando le singole docstring che causano problemi, ma il problema è purtroppo molto più sistemico. Senza un luogo centralizzato in cui trovare la documentazione, avremo semplicemente sempre più copie di una documentazione sempre più dettagliata ripetuta ovunque venga utilizzato ciascuno di questi tipi impliciti, rendendo ancora più difficile per gli utenti principianti trovare il parametro di cui hanno bisogno. Tuttavia, anche il sistema attuale, che costringe gli utenti a mettere insieme lentamente il proprio modello mentale di ogni tipo implicito tramite un'esplorazione in stile wiki della nostra documentazione o in modo frammentario dagli esempi di StackOverflow, non è sostenibile.

Obiettivo finale

Idealmente, qualsiasi menzione di un tipo implicito dovrebbe rimandare a una singola pagina che descrive tutti i possibili valori che il tipo può assumere, ordinati dal più semplice e comune al più avanzato o esoterico. Invece di utilizzare uno spazio visivo prezioso nella documentazione dell'API di primo livello per elencare in modo frammentario tutti i possibili tipi di input per un determinato parametro, possiamo utilizzare lo stesso spazio per fornire una descrizione in parole semplici dell'astrazione di rappresentazione che il parametro è destinato a controllare.

Per utilizzare di nuovo l'esempio di linestyle, quello che vogliamo nei documenti di LineCollection è solo:

  1. Un link ai documenti completi per gli input consentiti (una combinazione di quelli trovati in Line2D.set_linestyle e nel tutorial su stile di linea).
  2. Una descrizione in parole semplici di ciò che si intende ottenere con il parametro. Per gli utenti esperti di matplotlib, questo è evidente dal nome del parametro, ma per i nuovi utenti non è necessariamente così.

L'aspetto di questo codice nelle attuali documentazioni di LineCollection è simile a python """""" linestyles: `LineStyle` or list thereof, default: :rc:`lines.linestyle` ('-') A description of whether the stroke used to draw each line in the collection is dashed, dotted or solid, or some combination thereof. """""" dove il riferimento al tipo LineStyle viene risolto da Sphinx per indicare un unico insieme autorevole e completo di documentazione su come Matplotlib tratta gli stili di linea.

Vantaggi

Alcune potenti funzionalità di questo approccio includono

  1. Rendere visibile l'intera portata di ogni funzione in testo normale (senza necessità di clic).
  2. Rendendo visibile l'opzione predefinita (senza clic). Spesso è sufficiente vedere l'opzione predefinita per ricordare agli utenti di tornare.
  3. Fornisci una descrizione completa delle opzioni ""più comuni"" e ""più semplici"" per un parametro facilmente disponibile durante la navigazione (con un solo clic).
  4. Scoprire funzionalità e metodi di immissione più potenti è semplice come ""scorrere verso il basso"" per visualizzare opzioni più avanzate (con un solo clic).
  5. Fornisci una strategia centralizzata per collegare la documentazione di ""API"" di primo livello ai ""tutorial"" pertinenti.
  6. Evita l'esplosione della documentazione API, in cui la scansione delle molte opzioni possibili per ogni parametro rende le singole docstrings poco maneggevoli.

Altri vantaggi di questo approccio rispetto ai documenti attuali sono:

  1. I documenti hanno meno probabilità di diventare obsoleti, grazie alla centralizzazione.
  2. Canonicalizzazione di molti ""standard impliciti"" di matplotlib (come i ""limiti"" rispetto a un ""esenzioni") che attualmente devono essere appresi leggendo il codice.
  3. Il processo evidenzierebbe i problemi di coerenza dell'API in un modo che può essere tracciato più facilmente tramite lo strumento di monitoraggio dei problemi di GitHub, contribuendo al processo di miglioramento dell'API.
  4. Tempi di compilazione dei documenti più rapidi, grazie a una diminuzione significativa della quantità di testo da analizzare.

Implementazione

I miglioramenti descritti sopra richiederanno due importanti interventi per i quali un autore tecnico dedicato sarà di inestimabile valore. La prima consiste nel creare una pagina ""tutorial"" centralizzata per tipo implicito. Per farlo, dovrai collaborare con il team di sviluppatori di base per identificare un elenco concreto di tipi impliciti la cui documentazione sarebbe utile per gli utenti (in genere perché contengono funzionalità potenti e nascoste della nostra libreria la cui documentazione è attualmente disponibile solo in tutorial difficili da trovare). Per ogni tipo implicito, sintetizzerò poi i vari tutorial, documenti API e pagine di esempio pertinenti in un'unica fonte autorevole di documentazione che può essere collegata a qualsiasi punto in cui viene fatto riferimento a quel determinato tipo.

Una volta completata la documentazione centralizzata per un determinato tipo implicito, inizia il secondo impegno principale: sostituire la documentazione dell'API esistente con link alla nuova documentazione, con l'obiettivo di semplificare al massimo l'esperienza di utilizzo della nuova documentazione, sia per chi utilizza l'utilità help() integrata di Python sia per chi naviga nella nostra documentazione online.

Sebbene il formato esatto della documentazione proposta qui sia soggetto a modifiche con l'evoluzione del progetto, ho collaborato con il team di base di Matplotlib durante le loro ""chiamate per sviluppatori"" settimanali per stabilire un consenso sul fatto che la strategia proposta qui sia l'approccio più pratico, utile e tecnicamente gestibile per iniziare a documentare questi ""tipi impliciti"" (le note su queste chiamate sono disponibili su hackmd). Utilizzerò l'infrastruttura esistente dei ""tutorial"" per le fasi iniziali della creazione della documentazione centralizzata per ogni tipo implicito, in modo da poter fare facilmente riferimento a queste pagine come segue, senza dover creare nuovi classi pubblici (di nuovo, utilizzando la documentazione di LineCollection come esempio):

""""""
linestyles: LineStyle or list thereof, default: :rc:`lines.linestyle` ('-')
    A description of whether the stroke used to draw each line in the collection
    is dashed, dotted or solid, or some combination thereof. For a full
    description of possible LineStyle's, see :doc:`tutorials/types/linestyle`.
""""""

In futuro, potremmo facilmente modificare l'ortografia di questi riferimenti quando il team di sviluppatori principali avrà raggiunto un accordo sulla strategia migliore a lungo termine per integrare la nostra nuova documentazione relativa ai ""tipi"" nelle classi Python autentiche, ad esempio come da me proposto nella Proposta di miglioramento di Matplotlib 30.

Infine, l'elenco preliminare dei tipi impliciti che propongo di documentare in questa stagione di Documenti Google è:

  1. capstyle
  2. joinstyle
  3. bounds
  4. extents
  5. linestyle
  6. colors/lists of colors
  7. colornorm/colormap
  8. tick formatters

Una versione aggiornata di questo documento è disponibile sul nostro canale Discourse.