Ai fini di questa demo, ho creato un modulo Python demo.py che contiene una classe e tre funzioni di base (tutte annotate con docstring ad eccezione di una funzione). È per questo modulo che creerò la documentazione in questo articolo. Il contenuto di questo modulo demo.py è riportato di seguito:
1. Configurazione
La prima cosa è configurare tutto. Dovrai installare VS Code e impostare un nuovo progetto insieme a Sphinx. Ci sono alcune opzioni qui. Puoi a) impostare un nuovo progetto utilizzando Cookiecutter (dove verrà generata la relativa configurazione di Sphinx insieme alle directory standardizzate) oppure b) creare la tua struttura di progetto e installare Sphinx separatamente.
opzione A: installa Cookiecutter
Nel terminale, installa Cookiecutter e quindi crea un nuovo progetto:
pip install cookiecutter
cookiecutter https://github.com/drivendata/cookiecutter-data-science
Successivamente, rispondi alle domande che appaiono nella finestra del terminale e il tuo nuovo progetto verrà creato. Il framework Sphinx verrà archiviato nella directory /docs del tuo progetto.
opzione B – Avvio rapido di Sphinx
Se il modello Cookiecutter non soddisfa la tua fantasia, puoi creare la struttura del tuo progetto da zero e installare sphinx. È una buona idea creare una directory di documentazione e installarvi sphinx. Nel terminale:
mkdir docs
cd docspip install sphinx
sphinx-quickstart
2. Comprendere la struttura delle cartelle di Sphinx
Dopo aver installato Sphinx utilizzando una delle opzioni di cui sopra, verranno visualizzati alcuni file nella directory della documentazione del tuo progetto. IL conf.py file è il file di configurazione chiave che modificherai per personalizzare la tua documentazione: maggiori dettagli nella sezione successiva. IL index.rst file funge da contenuto per la documentazione. Puoi trovare maggiori informazioni su index.rst file Qui. IL getting-started.rst E commands.rst i file sono modelli suggeriti per la documentazione. Puoi rimuoverli se necessario. I file make (make.bat E Makefile) vengono utilizzati per realizzare effettivamente la documentazione. Non è necessario modificarli, ma li richiamerai nella finestra del terminale quando sarai pronto per creare la documentazione.
3. File Conf.py
Il file di configurazione è dove avviene la magia. Questo file viene utilizzato durante il processo di creazione e quindi è fondamentale averlo impostato correttamente. Di seguito sono riportati alcuni passaggi per modificare il file conf.py file:
Decommentare la riga sys.path (riga 20 nella mia configurazione):
# sys.path.insert(0, os.path.abspath('.'))
Cambia il percorso di os.path.abspath alla posizione relativa del codice che desideri documentare (rispetto al file conf.py file). Ad esempio, i moduli Python che voglio documentare si trovano nella directory src/ del mio progetto. Quindi cambierò os.path.abspath con l'aspetto nella directory /src che si trova nella cartella principale del conf.py file. È possibile specificare la posizione relativa utilizzando il file . e / sintassi:
sys.path.insert(0, os.path.abspath('../src'))"""
# you can use the following syntax to specify relative locations:
'.' # current path of conf.py
'..' # parent path of conf.py
'../..' # parent of the parent path of conf.py
"""
Aggiungi le estensioni pertinenti. Dovrai aggiungere alcune estensioni al file conf.py file per ottenere funzionalità extra durante la creazione della documentazione. Sono tutti opzionali e puoi divertirti esplorando le diverse estensioni disponibili Qui. Ecco le 5 estensioni che consiglio come minimo:
- sphinx.ext.autodoc — utilizzare la documentazione da docstring
- autodocsum – genera un riepilogo tabellare di tutte le docstring nella parte superiore della pagina html elencando solo i riepiloghi delle docstring. Utile quando hai molte docstring. Nota. dovrai installare pip autodocsumm nel terminale.
- sfinge.ext.napoleone – consente a Sphinx di analizzare le docstring di Google
- sphinx.ext.viewcode — aggiunge un collegamento a una pagina html contenente il codice sorgente per ciascun modulo
- sphinx.ext.copertura — fornisce un riepilogo di quante classi/funzioni ecc. hanno docstring. Una buona copertura significa che una codebase è ben spiegata.
Ecco come includere queste estensioni nel file conf.py file (riga 29 nella mia configurazione):
# add in the extension names to the empty list variable 'extensions'
extensions = (
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'autodocsumm',
'sphinx.ext.coverage'
)# add in this line for the autosummary functionality
auto_doc_default_options = {'autosummary': True}
Cambia il tema. Il tema predefinito della documentazione è abbastanza pulito, anche se potresti preferire giocare con diverse opzioni cambiando la variabile 'html_theme' (riga 94 nella mia configurazione) da 'default' a uno dei temi standard opzioni del tema o qualche opzioni di terzi. In questa demo mostrerò i temi predefiniti e Leggi i documenti.
html_theme = 'sphinx_rtd_theme' # read the docs theme. This variable is 'default' by default.
Nota. dovrai installare tramite pip eventuali temi non standard (di terze parti).
4. Crea le pagine html
Ora che il tuo conf.py è impostato e hai splendide docstring nel tuo codice, siamo pronti per fare un po' di scraping e creare alcune pagine html.
Genera i primi file .rst dei tuoi pacchetti Python
Questi file sono i precursori delle pagine html e sono il formato nativo di Sphinx. Questi devono essere generati prima di creare i file html. Utilizzerai il sfinge.apidoc comando, che utilizza l'estensione autodoc per individuare tutti i moduli Python (ad esempio eventuali file .py) all'interno della posizione sys.path specificata nel conf.py file. Ci sono alcuni parametri facoltativi da includere quando si utilizza il comando apidoc che puoi trovare nel file documentazionema ho usato il seguente modello:
Nota. nel terminale, cambia la directory nella radice del progetto per eseguire il codice seguente.
sphinx-apidoc -f -o output_dir module_dir/
-F (forza la sovrascrittura di tutti i file generati esistenti).
-o dir_output (directory in cui posizionare i file di output. Se non esiste, viene creata). Nota. sostituisci 'output_dir' con un nome di directory a tua scelta. Ho impostato il mio nella directory /docs.
dir_modulo (posizione dei pacchetti Python da documentare)
Dopo aver eseguito questo comando, nella cartella documenti dovrebbero essere presenti i file .rst appena generati.
Notare che sono stati generati due nuovi file .rst: data.rst E modules.rst. Inoltre modules.rstverrà generato un file .rst per ogni directory che contiene almeno un modulo Python. Nel mio esempio, data.rst viene generato poiché ho salvato il mio file demo.py nella cartella src/data directory. Se disponi di più directory di moduli Python nella posizione specificata in sys.path nel file conf.py file, verranno generati più file .rst. Nota. Questi file non contengono ancora la documentazione recuperata, contengono solo le informazioni necessarie affinché Autodoc crei i file html nel passaggio successivo.
Modifica il file index.rst
Ricordare, index.rst funge da pagina di contenuto quindi dobbiamo modificare questo file per includere tutti i moduli Python che vogliamo documentare. Fortunatamente, il modules.rst fa riferimento alla posizione di origine di tutti i moduli Python identificati in sys.path, quindi puoi semplicemente aggiungere questo file a index.rst.
Per fare ciò, apri il file index.rst file e aggiungi “moduli” sotto la sezione toctree (albero del sommario). Assicurati che ci sia una linea tra il parametro :max Depth: e i nomi dei file .rst.
Nota. 'getting-started' e 'commands' saranno già presenti nel file index.rst. Puoi cancellarli da questo file se non vuoi generare pagine html (anche se una pagina 'introduttiva' è probabilmente una buona idea!)
Crea file html
Ora possiamo usare i file make nella directory della documentazione per creare i file html. Questi file verranno visualizzati nel file _build/html/ directory all'interno della cartella della documentazione. Puoi visualizzarli in anteprima nel codice VS se scarichi l'estensione “Anteprima HTML”.
Cambia la directory in cui si trova il file make.bat ed esegui il seguente comando nel terminale cmd:
make html
Nota. se stai utilizzando il terminale Windows PowerShell (anziché cmd), utilizza la seguente sintassi:
.\make.bat html
Il miglior consiglio. se quando si utilizza il comando make html viene visualizzato un avviso che indica “autodoc: importazione del modulo non riuscita”, è molto probabile che autodoc non sia in grado di trovare i moduli poiché sys.path non è stato configurato correttamente in conf.py. Assicurati che punti alla directory in cui si trovano i tuoi moduli Python.
Modifica di file html
Se desideri modificare le tue docstring e aggiornare i tuoi file html con le modifiche, puoi farlo utilizzando il seguente comando:
make clean html
Diamo un'occhiata alla nostra documentazione!
Come ho detto sopra, ho creato della documentazione del mio modulo Python demo.py in due temi diversi visti nelle immagini sottostanti; 'default' (immagine a sinistra) e 'Leggi i documenti' (immagine a destra). Il contenuto è identico ma l'aspetto grafico è diverso. Prendiamo nota delle caratteristiche principali:
- Barra di navigazione sul lato sinistro
- Un riepilogo di tutte le classi o funzioni appartenenti al modulo in tabelle nella parte superiore della pagina (grazie all'estensione 'autodocsumm')
- Elenco dettagliato dei componenti docstring per tutte le funzioni e classi sotto il riepilogo
Fonte: towardsdatascience.com
