In questo articolo, esamineremo le (molto) basi della generazione di documentazione da docstrings nel tuo codice Python. È un po ‘ una macinatura, ma dopo averlo fatto una volta, sarà facile ripetere il processo in ogni nuovo progetto.

Per i nostri scopi, assumeremo che tu (1) credi nel valore di documentare il tuo codice; (2) desideri generare documenti dai tuoi documenti e (3), hai scelto di usare Sphinx per realizzare il lavoro.

Infine, si presume che sia già stato configurato un ambiente virtuale distinto per l’applicazione. Per chi fosse interessato, mi piace molto il gestore dell’ambiente pyenv. Ha anche un pratico programma di installazione.

È necessario installare sphinx tramitepip. Come minimo avrai bisogno della versione 1.3, ma a meno che tu non abbia una buona ragione, dovresti installare la versione più recente.

$ pip install sphinx

Passo 2: Imposta il tuo progetto con Quickstart

Quando installi il pacchetto sphinx, vengono impostate anche alcune utility da riga di comando.

Uno di questi,sphinx-quickstart genererà rapidamente un file di configurazione di base e una struttura di directory per la documentazione.

Esegui questo comando nella directory di base del tuo progetto (cioè la radice del repository Git). Ti chiederà una serie di domande che determineranno le sue azioni. Generalmente puoi accettare i valori predefiniti, ma ecco alcuni suggerimenti su quando deviare dal default:

Dopo che il programma è stato eseguito, noterai che una nuova cartella ./docs esiste nella directory del progetto. Inoltre, ci sono tre nuovi file in quella cartella: conf.pyindex.rst eMakefile.

Passo 3: Regolazione del conf.py File

Il file predefinitoconf.py generato dall’utilità quickstart è lungo circa 170 righe, quindi non includerò l’intera cosa qui. Ci sono tuttavia un paio di elementi che dobbiamo aggiornare prima di continuare.

Dì a Sphinx la posizione del tuo pacchetto Python

La prima cosa che dobbiamo fare è indicare dove il pacchetto Python che contiene il codice del tuo programma è in relazione al fileconf.py. Se la struttura della directory è simile a questa:

Sarà necessario indicare nel conf.py file Sfinge deve andare “su” di un livello di directory per trovare il pacchetto Python.

Il posto dove mettere questo è alla fine della prima sezione del file di configurazione. Poco prima delle impostazioniGeneral Configuration, vedrai questo:

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

Se non è stato commentato, indicherebbe che il pacchetto si trova nella stessa directory del fileconf.py. Dovrai cambiarlo in questo modo:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Aggiungi “Napoleon” all’elenco delle estensioni Sphinx per usare

Fuori dalla scatola, Sphinx comprende solo le docstring scritte nel tradizionale reStructuredText. Se hai avuto il privilegio di lavorare con tali docstring, saprai che sono un dolore da scrivere e per niente umano da leggere quando li guardi direttamente nel codice sorgente.

L’estensione Napoleon consente a Sphinx di comprendere le docstring scritte in altri due formati popolari: NumPy e Google.

Tutto quello che dobbiamo fare è aggiungere sphinx.ext.napoleon alla lista extensions. Quando hai finito, dovrebbe essere simile a questo:

extensions = 

Passo 4: Aggiorna indice.rst

A questo punto, potremmo effettivamente eseguire il processo di compilazione per generare la nostra documentazione. Ma sarebbe piuttosto deludente. Ecco cosa otterremmo:

Quanto vorrei per Sfinge di andare a trovare il nostro le docstring per noi e disporli bene senza alcuna configurazione, non è molto che di magico.

Per andare avanti, dovremo fare alcune piccole modifiche al nostro fileindex.rst, che attualmente assomiglia a questo:

Iniziamo sbarazzandoci del commento in alto che è solo rumore:

Ora, mentre ci sono un certo numero di cose che potremmo fare qui, ci limiteremo al minimo indispensabile per mantenere questo post a una lunghezza alquanto ragionevole.

Vedi quella riga.. toctree::? Questo è ciò che Sphinx chiama una direttiva. Dobbiamo aggiungere le direttive autodoc al nostro fileindex.rst in modo che Sphinx sappia su quali oggetti di codice desideriamo utilizzare l’estensione autodoc.

Andrò avanti e aggiungerò uno che indica a Sphinx che voglio che documenti i membri pubblici del miomain.py modulo all’interno delmy_project pacchetto:

Passo 5: Scrivi le tue Docstrings

Non copriremo il come scrivere docstrings in Numpy o Google style in questo post.

Tuttavia, ecco il codice damain.py che contiene un paio di semplici docstring in stile NumPy che verranno rilevati dalla nostra direttiva autodoc:

Punto 6: Genera i tuoi documenti!

Ora è il momento di raccogliere i frutti del tuo lavoro. Assicurati di essere nella directory ./docs ed esegui quanto segue: make html

Se hai seguito fino ad ora, dovresti vedere qualcosa di simile:

Finché vedi quel glorioso messaggio build succeeded alla fine, sei pronto per iniziare la tua ricerca.andate a vedere la vostra bella creazione.

Alla riga di comando, eseguiopen _build/html/index.html (o apri manualmente quella pagina nel tuo browser) e dovresti vedere qualcosa del genere:

Prossimi Passi

Abbiamo appena scalfito la superficie di qui e ci sono un sacco di verruche ancora presente nel nostro semplice documentazione.

Nel prossimo post su questo argomento, approfondiremo le direttive dell’estensione autodoc e otterremo un maggiore controllo del contenuto e dell’aspetto della nostra documentazione.