MEP10: consistenza Docstring #

Stato n.

Progresso

Questo è ancora uno sforzo in corso

Filiali e Pull request #

Estratto n.

matplotlib ha una grande quantità di incoerenza tra le docstring. Questo non solo rende i documenti più difficili da leggere, ma è anche più difficile per i contributori, perché non sanno quali specifiche seguire. Dovrebbe esserci una chiara convenzione di docstring che viene seguita in modo coerente.

L'organizzazione della documentazione API è difficile da seguire. Alcune pagine, come pyplot e axis, sono enormi e difficili da sfogliare. Dovrebbero invece esserci brevi tabelle riassuntive che rimandano a documentazione dettagliata. Inoltre, alcune delle docstring stesse sono piuttosto lunghe e contengono informazioni ridondanti.

La compilazione della documentazione richiede molto tempo e utilizza uno make.py script piuttosto che un Makefile.

Descrizione dettagliata #

Sono disponibili numerosi nuovi strumenti e convenzioni da quando matplotlib ha iniziato a utilizzare Sphinx che semplificano la vita. Di seguito è riportato un elenco di modifiche proposte alle docstring, la maggior parte delle quali coinvolge queste nuove funzionalità.

Formato docstring Numpy #

Numpy docstring format : questo formato divide la docstring in sezioni chiare, ciascuna con regole di analisi diverse che rendono la docstring facile da leggere sia come testo non elaborato che come HTML. Potremmo prendere in considerazione alternative o inventarne di nostre, ma questa è una scelta forte, poiché è ben utilizzata e compresa nella comunità Numpy/Scipy.

Riferimenti incrociati #

La maggior parte delle docstring in matplotlib usano "ruoli" espliciti quando si collegano ad altri elementi, ad esempio: :func:`myfunction`. A partire da Sphinx 0.4, esiste un "default_role" che può essere impostato su "obj", che si collegherà polimorficamente a un oggetto Python di qualsiasi tipo. Questo permette di scrivere `myfunction`invece. Ciò rende le docstring molto più facili da leggere e modificare come testo non elaborato. Inoltre, Sphinx consente di impostare un modulo corrente, quindi collegamenti come `~matplotlib.axes.Axes.set_xlim` potrebbero essere scritti come `~axes.Axes.set_xlim`.

Sovrascrivere le firme #

Molti metodi in matplotlib usano la sintassi *argsand **kwargsper gestire dinamicamente gli argomenti delle parole chiave accettati dalla funzione o per delegare a un'altra funzione. Questo, tuttavia, spesso non è utile come firma nella documentazione. Per questo motivo, molti metodi matplotlib includono qualcosa del tipo:

def annotate(self, *args, **kwargs):
    """
    Create an annotation: a piece of text referring to a data
    point.

    Call signature::

      annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)
    """

Questo non può essere analizzato da Sphinx ed è piuttosto prolisso nel testo grezzo. A partire da Sphinx 1.1, se il autodoc_docstring_signaturevalore di configurazione è impostato su True, Sphinx estrarrà una firma sostitutiva dalla prima riga della docstring, consentendo questo:

def annotate(self, *args, **kwargs):
    """
    annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)

    Create an annotation: a piece of text referring to a data
    point.
    """

La firma esplicita sostituirà quella effettiva di Python nella documentazione generata.

Collegamento anziché duplicazione #

Molte delle docstring includono lunghi elenchi di parole chiave accettate interpolando le cose nella docstring al momento del caricamento. Questo rende le docstring molto lunghe. Inoltre, poiché queste tabelle sono le stesse in molte docstring, inserisce molte informazioni ridondanti nei documenti, in particolare un problema nella versione stampata.

Queste tabelle dovrebbero essere spostate in docstring su funzioni il cui unico scopo è di aiuto. Le docstring che fanno riferimento a queste tabelle dovrebbero collegarsi ad esse, piuttosto che includerle alla lettera.

estensione di riepilogo automatico #

L'estensione di riepilogo automatico Sphinx dovrebbe essere utilizzata per generare tabelle di riepilogo, che si collegano a pagine separate di documentazione. Alcune classi che hanno molti metodi (ad esempio Axes) dovrebbero essere documentate con un metodo per pagina, mentre le classi più piccole dovrebbero avere tutti i loro metodi insieme.

Esempi di collegamento alla documentazione pertinente #

Gli esempi, sebbene utili per illustrare come utilizzare una funzionalità, non rimandano alle relative docstring. Ciò potrebbe essere risolto aggiungendo docstring a livello di modulo agli esempi e quindi includendo quella docstring nel contenuto analizzato nella pagina di esempio. Queste docstring potrebbero facilmente includere riferimenti a qualsiasi altra parte della documentazione.

Documentazione che utilizza help() rispetto a un browser #

L'utilizzo del markup Sphinx nel sorgente consente di avere documenti di bell'aspetto nel browser, ma il markup rende anche il testo non elaborato restituito utilizzando help() un aspetto terribile. Uno degli obiettivi del miglioramento delle docstring dovrebbe essere quello di far sembrare buoni entrambi i metodi di accesso ai documenti.

Implementazione n.

  1. Le estensioni numpydoc dovrebbero essere attivate per matplotlib. C'è una domanda importante se questi debbano essere inclusi nell'albero dei sorgenti matplotlib o usati come dipendenza. L'installazione di Numpy non è sufficiente per ottenere le estensioni numpydoc: è una procedura di installazione separata. In ogni caso, nella misura in cui richiedono la personalizzazione per le nostre esigenze, dovremmo sforzarci di presentare tali modifiche a monte e non biforcarle.

  2. Esamina manualmente tutte le docstring e aggiornale al nuovo formato e alle nuove convenzioni. L'aggiornamento dei riferimenti incrociati (da `:func:`myfunc`a `func`) può essere semiautomatico. Questo è un lavoro molto impegnativo e forse questo lavoro dovrebbe essere suddiviso in base al modulo in modo che nessun singolo sviluppatore ne sia sovraccaricato.

  3. Riorganizza i documenti API utilizzando il riepilogo automatico e i file sphinx-autogen. Si spera che questo dovrebbe avere un impatto minimo sulla documentazione narrativa.

  4. Modificare il generatore di pagine di esempio ( gen_rst.py) in modo che estragga la docstring del modulo dall'esempio e la includa in una parte non letterale della pagina di esempio.

  5. Utilizzare sphinx-quickstartper generare un Makefile Sphinx di nuovo stile. Le seguenti funzionalità nella corrente make.pydovranno essere affrontate in qualche altro modo:

    • Copia di alcuni contenuti statici

    • Specificare una build "piccola" (solo file PNG a bassa risoluzione per esempi)

I passaggi 1, 2 e 3 sono interdipendenti. 4 e 5 possono essere eseguiti indipendentemente, sebbene 5 abbia una certa dipendenza da 3.

Compatibilità con le versioni precedenti #

Poiché ciò riguarda principalmente le docstring, dovrebbe esserci un impatto minimo sulla compatibilità con le versioni precedenti.

Alternative #

Nessuno ancora discusso.