Progetto Matplotlib

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.

Riepilogo del progetto

Organizzazione open source:
Matplotlib
Technical writer:
Brunobeltran
Nome progetto:
Migliorare la rilevabilità delle funzionalità standardizzando la documentazione dei tipi "impliciti"
Durata del progetto:
Lunga esecuzione (5 mesi)

Project description

Motivazione

Storicamente, l'API di matplotlib si è affidata molto ai "tipi impliciti" di string-as-enum. Oltre a imitare l'API di matlab, queste stringhe di parametri consentono all'utente di passare valori semanticamente ricchi come argomenti alle funzioni matplotlib, senza dover importare esplicitamente un valore enumerato o precedere verbalmente un valore enum effettivo solo per passare opzioni di tracciamento di base (ad esempio, plt.plot(x, y, linestyle='solid') è più facile da digitare e meno ridondante rispetto a plt.plot(x, y, linestyle=mpl.LineStyle.solid)).

Da allora, molti di questi tipi impliciti stringa come enum si sono evoluti in funzionalità più sofisticate. Ad esempio, linestyle ora può essere una stringa o una tupla a due tuple di sequenze e un MarkerStyle ora può essere una stringa o matplotlib.path.Path. Sebbene questo sia vero per molti tipi impliciti, MarkerStyle è l'unico (per quanto ne so) che ha lo stato di essere stato aggiornato a una classe Python adeguata.

Poiché questi tipi impliciti non sono classi a sé stanti, Matplotlib ha storicamente dovuto implementare le proprie soluzioni per centralizzare la documentazione e la convalida di questi tipi impliciti (ad es. il pattern di interpolazione docstring docstring.interpd.update e il pattern di convalida cbook._check_in_list), invece di utilizzare le Toolchain standard fornite dalle classi Python (ad es. docstring e i pattern di convalida__init__).

Sebbene queste soluzioni abbiano funzionato bene per noi, la mancanza di una posizione esplicita per documentare ogni tipo implicito fa sì che la documentazione sia spesso difficile da trovare, tabelle di grandi dimensioni di valori consentiti vengono ripetute in tutta la documentazione e spesso manca completamente un'affermazione esplicita dell'ambito di un tipo implicito. Prendiamo ad esempio i documenti plt.plot, ad esempio: in ""Notes"", una descrizione del metodo di stile per le stringhe di formato e le stringhe di formato matlab menziona le opzioni linestyle, color e markers. Esistono molti altri modi per trasmettere questi tre valori rispetto a quelli indicati, ma per molti utenti questa è l'unica fonte di comprensione dei valori possibili per queste opzioni fino a quando non si imbatte in uno dei tutorial pertinenti. Una tabella degli attributi Line2D viene inclusa nel tentativo di mostrare al lettore le opzioni di cui dispone per controllare la trama. Tuttavia, mentre la voce linestyle funziona correttamente nel collegarsi a Line2D.set_linestyle (sono necessari due clic quando sono descritti i possibili input), le voci color e markers non lo fanno. color si collega semplicemente a Line2D.set_color, che non offre alcun tipo di intuizione sui tipi di input consentiti.

Si potrebbe sostenere che questo è un problema che può essere risolto semplicemente mettendo in ordine le singole docstring che causano problemi, ma sfortunatamente il problema è molto più sistemico di questo. Senza una posizione centralizzata in cui trovare la documentazione, ciò porterà semplicemente a un numero sempre maggiore di copie di documentazione sempre più dettagliata ripetuta ovunque sia utilizzato ognuno di questi tipi impliciti, il che rende particolarmente più difficile per gli utenti principianti trovare semplicemente il parametro di cui hanno bisogno. Tuttavia, anche il sistema attuale, che costringe gli utenti a comporre lentamente il proprio modello mentale di ogni tipo implicito attraverso l'attraversamento dello stile wiki-diving nella nostra documentazione, o frammentato dagli esempi di StackOverflow, non è sostenibile.

Obiettivo finale

Idealmente, qualsiasi menzione di un tipo implicito dovrebbe essere collegato 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. Anziché utilizzare un prezioso spazio visivo nella documentazione dell'API di primo livello per enumerare frammentariamente tutti i possibili tipi di input per un determinato parametro, possiamo quindi utilizzare lo stesso spazio per fornire una descrizione in parole semplici dell'astrazione di tracciamento che il parametro deve controllare.

Per utilizzare di nuovo l'esempio di linestyle, nei documenti LineCollection vorremmo che aggiungeremo:

  1. Un link per completare la documentazione relativa agli input consentiti (una combinazione di quelli disponibili in Line2D.set_linestyle e nel tutorial sullo stile linea).
  2. Una descrizione con parole semplici dello scopo del parametro. Per gli utenti esperti, questo è evidente dal nome del parametro, ma per i nuovi utenti non è necessario.

L'aspetto sarebbe simile nei documenti effettivi di LineCollection solo 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. """""" in cui il riferimento al tipo LineStyle verrebbe risolto da Sphinx per indicare l'unico set di documentazione autorevole e completo su come Matplotlib gestisce gli stili di linea.

Vantaggi

Alcune potenti funzionalità di questo approccio includono

  1. Estendere l'estensione completa di ciò che ogni funzione è in grado di mettere in evidenza in testo normale (senza clic necessari).
  2. Rendere visibile l'opzione predefinita (senza clic). Vedere l'opzione predefinita spesso è sufficiente per rinfrescare la memoria degli utenti di ritorno.
  3. Fornisci una descrizione completa delle opzioni ""più comuni"" e ""più semplici"" per un parametro facilmente disponibili durante la navigazione (con un solo clic).
  4. Fai in modo che il processo di scoperta di funzionalità e metodi di immissione più potenti sia semplice come "scorri verso il basso" per visualizzare opzioni più avanzate (con un solo clic).
  5. Fornisci una strategia centralizzata per collegare i documenti ""API"" di primo livello ai "tutorial" pertinenti.
  6. Evita l'esplosione dei documenti API, dove la scansione delle numerose opzioni possibili per ciascun parametro rende ingombranti le singole docstring.

Altri vantaggi di questo approccio rispetto ai documenti correnti sono:

  1. È meno probabile che i documenti diventino inattivi a causa della centralizzazione.
  2. Canonicalizzazione di molti ""standard impliciti"" di matplotlib (come i ""limiti"" e le ""estesi"") di matplotlib che attualmente devono essere appresi leggendo il codice.
  3. Il processo evidenzia i problemi di coerenza delle API in modo che possano essere rilevati più facilmente tramite il tracker dei problemi GitHub, contribuendo al processo di miglioramento della nostra API.
  4. Tempi di creazione dei documenti più rapidi, a causa di diminuzioni significative della quantità di testo da analizzare.

Implementazione

I miglioramenti descritti sopra richiederanno due importanti sforzi per i quali un Technical Writer dedicato si rivelerà inestimabile. Il primo è creare una pagina "tutorial" centralizzata per tipo implicito. Ciò richiederà la collaborazione con il team di sviluppo principale per identificare un elenco concreto di tipi impliciti la cui documentazione sarebbe utile per gli utenti (in genere, perché contengono funzionalità nascoste potenti della nostra libreria la cui documentazione attualmente si trova solo in tutorial difficili da imbattersi). Per ogni tipo implicito, sintetizzerò quindi i vari tutorial, documenti dell'API e pagine di esempio pertinenti in un'unica fonte di documentazione autorevole 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 importante sforzo: sostituire la documentazione esistente dell'API con link alla nuova documentazione, con l'obiettivo di semplificare il più possibile l'esperienza di utilizzo effettiva di questa nuova documentazione, sia per chi utilizza l'utilità help() integrata di Python sia per chi consulta la nostra documentazione online.

Sebbene il formato esatto della documentazione qui proposto possa cambiare man mano che il progetto si evolve, ho lavorato con il team principale di Matplotlib durante le loro ""dev call" settimanali" per raggiungere un consenso sul fatto che la strategia proposta qui sia l'approccio più opportuno, utile e tecnicamente trattabile per iniziare a documentare questi ""tipi impliciti"" (sono disponibili note su queste chiamate). Utilizzerò l'infrastruttura esistente dei "tutorial" per le fasi iniziali della creazione della documentazione centralizzata per ogni tipo implicito, in modo da poter fare riferimento a queste pagine in modo semplice come segue, senza dover creare nuove classi pubbliche (nuovamente, utilizzando i documenti 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 poi cambiare facilmente il modo in cui questi riferimenti verranno scritti, una volta che il team di sviluppatori principale concorda sulla migliore strategia a lungo termine per incorporare la nostra nuova documentazione dei "tipi" in classi Python in buona fede, ad esempio come proposto da me nella Proposta di miglioramento di Matplotlib 30.

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

  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 nel nostro Discourse.