Come configurare Sphinx per documentare il tuo codice Python

Sphinx è uno degli strumenti più popolari per la generazione di documentazione. In tutta la comunità Python, gli sviluppatori utilizzano questo software gratuito e open source. Può estrarre il testo direttamente dal codice o dai file markdown e quindi utilizzarlo per generare documentazione in vari formati come testo normale, HTML, PDF ed EPUB.

Installazione della Sfinge

Prima di configurare Sphinx, dai un'occhiata a cosa fa e ad alcune delle sue caratteristiche principali.

Cos'è la Sfinge e cosa fa?

Come accennato, Sphinx è un generatore di documentazione. Per impostazione predefinita, utilizza il linguaggio di markup reStructuredText (RST), ma tramite estensioni di terze parti può anche usa Markdown, il popolare linguaggio di markup del testo normale. Quindi converte questi file RST o markdown in HTML, PDF, pagine di manuale o altri formati che preferisci.

Alcune delle funzionalità che Sphinx include sono:

• Capacità di generare documentazione dal codice.
• Possibilità di incrociare diverse pagine del documento utilizzando collegamenti automatici per funzioni, classi, citazioni e termini del glossario.
• Evidenziazione della sintassi per i blocchi di codice.
• Supporto per temi che possono modificare l'aspetto dei documenti.
• Facile definizione dell'albero del documento attraverso un sommario.
• Possibilità di integrazione con estensioni di terze parti per aggiungere ulteriori funzionalità ai documenti come il test di frammenti di codice.

Installazione di Sphinx

Prima di installare Sphinx, assicurati di averlo Python 3 installato nel tuo ambiente di sviluppo. È quindi possibile utilizzare il gestore di pacchetti pip per installare Sphinx eseguendo il seguente comando nel terminale:

pip installa sfinge

Questo scaricherà e installerà Sphinx e le sue dipendenze.

Dopo l'installazione, eseguire quanto segue nel prompt dei comandi.

sphinx-build --versione

Se tutto ha funzionato correttamente, dovresti vedere il numero di versione del pacchetto Sphinx che hai appena installato.

Creazione di un nuovo progetto Sphinx

Dopo aver installato Sphinx, vai alla tua directory di lavoro ed esegui il comando sphinx-quickstart per creare un nuovo progetto Sphinx.

sfinge-quickstart

Questo comando ti chiederà di rispondere a una serie di domande su come configurare il tuo progetto Sphinx. Puoi specificare il nome del progetto e utilizzare le opzioni predefinite per le altre domande. In futuro, potresti voler personalizzare le risposte in base al tuo progetto.

Se elenchi il contenuto della tua directory, vedrai che questo comando crea alcuni file per te. Il file conf.py contiene i valori di configurazione e il file index.rst funge da pagina di benvenuto della tua documentazione. La directory di compilazione ospiterà la documentazione generata e Sphinx utilizza un Makefile (make.bat su Windows) per creare la documentazione.

Scrivere documentazione usando Sphinx

Il file index.rst nella radice della tua directory è la home page della tua applicazione. Quindi, aprilo con un editor di testo come VS Code o qualsiasi altro buon editor di codice gratuito— per modificarlo.

Puoi modificare index.rst come ritieni opportuno, ma una cosa che dovrebbe almeno avere è la direttiva root toctree (albero del sommario). Questo è essenziale in quanto collega più file a un'unica gerarchia di documenti.

Per aggiungere documentazione al file index.rst, puoi utilizzare il markup RST.

Ad esempio, considera un file index.rst per il modulo math_utils. Questo file potrebbe includere una breve panoramica dello scopo del modulo e un sommario che collega ad altre pagine della documentazione.

Benvenuti in Math Utils
.. toctree::
 :profondità massima: 2
Iniziare

Per utilizzare questo modulo, avrai bisogno di quanto segue:
* Python installato.
* Un editor di testo
Utilità matematiche

Il modulo `math-utils` fornisce funzioni matematiche di base come l'addizione e
sottrazione.

Puoi aggiungere più file .rst se necessario. Ad esempio, è possibile creare una guida per i contributi in un file denominato contribuendo.rst contenente le seguenti linee guida per i contributi.

Guida contribuente
Diamo il benvenuto a contributi al nostro progetto! Ecco alcune linee guida per
contributo:
- Fork del progetto su GitHub.
- Apporta le tue modifiche su un nuovo ramo.
- Scrivi test per assicurarti che le tue modifiche funzionino correttamente.
- Invia una richiesta pull con le tue modifiche.
- Apportare le modifiche richieste.
Grazie per aver contribuito!

Puoi quindi collegare questo file da index.rst aggiungendo una nuova sezione alla direttiva toctree:

.. toctree::
 :profondità massima: 2
 :didascalia: Sommario

 contribuendo

Questo crea un nuovo elemento chiamato contributo nel sommario che porta l'utente alla pagina del contributo quando viene cliccato.

Dopo aver scritto la documentazione, il passo successivo è crearla. Qui, costruire la documentazione significa generare pagine HTML, manuali o PDF dai file RST.

Costruire la documentazione

Per creare la documentazione utilizzando Sphinx, dovrai eseguire il comando make html nella radice della cartella in cui si trova il makefile.

creare html

Dovresti vedere i file HTML nella cartella build. Se ci sono stati errori durante la compilazione, Sphinx ti avviserà nel terminale.

Per visualizzare la documentazione, apri il file index.html nel tuo browser:

Dovresti essere in grado di navigare fino alla guida per contribuire dal sommario.

Personalizzare la documentazione

In questo momento, la documentazione ha uno stile di base. Se vuoi personalizzarlo, magari aggiungendo i colori del tuo marchio, o anche aggiungendo una modalità oscura, puoi installarne e utilizzarne altri temi incorporati o crea il tuo tema personalizzato.

Per dimostrare, prova a cambiare il tema in quello chiamato natura:

1. Apri il file di configurazione Sphinx conf.py nella directory del tuo progetto Sphinx.
2. Cerca la riga che definisce l'opzione html_theme e modificala in natura
3. Salva il file di configurazione e ricostruisci la documentazione per vedere le tue modifiche.

Ecco come dovrebbe apparire la homepage della documentazione.

Se non desideri utilizzare i temi integrati, puoi sempre utilizzare un file tema Sfinge di terze parti Invece.

Documentare il tuo codice usando Docstrings

Sphinx genera la tua documentazione Python dal testo che scrivi nei file RST. Sebbene questo sia sufficiente in alcuni casi, potresti anche voler utilizzare docstring nel tuo codice a livello di modulo.

Le docstring vivono direttamente all'interno dei file sorgente del tuo progetto. Ti consentono di descrivere cosa fa il codice, fornire esempi e persino creare test per quegli esempi. Dopo aver scritto le docstring, puoi generare la documentazione da esse utilizzando Sphinx.