Un semplice tutorial su come documentare il tuo progetto Python usando Sphinx e Rinohtype

Documentare il codice è una delle attività che non voglio davvero fare, ma lo farò comunque per i voti.

Questo è probabilmente quello che mi sentirai quando ero uno studente di informatica del primo anno. Ho trovato noioso e inutile documentare il codice poiché so già cosa fa il mio codice e l'unica persona che probabilmente lo leggerà è il professore che lo controlla.

Non ho capito la sua importanza fino a quando un giorno, ho avuto bisogno di guardare quel codice non documentato che ho scritto anni fa come riferimento e invece di limitarmi a sfogliarlo, ho passato molto tempo confuso su come ho strutturato il progetto e persino come eseguirlo.

Oggi ci sono molti strumenti disponibili per aiutarci a documentare il codice. Di recente ho appreso degli strumenti che semplificano la creazione di una documentazione intelligente e bella. Due di questi sono Sfinge e Rinohtype.

Sphinx, scritto da Georg Brandl e concesso in licenza con la licenza BSD, è stato originariamente creato per la documentazione di Python e ha eccellenti strutture per la documentazione di progetti software in varie lingue (Sphinx-doc.org, 2018).

Rinohtype, associato a Sphinx, offre una moderna alternativa a LaTeX. Fornisce un backend Sphinx che consente di generare documenti PDF (Machiels) professionalmente composti.

In questo tutorial, userò Sphinx e Rinohtype per produrre un file di documentazione HTML e PDF rispettivamente per un semplice progetto API che ho scritto che gestisce un elenco di record dell'insegnante (Github Project Link).

  1. Clona il progetto ed elimina / sposta la cartella dei documenti in modo che tu possa seguirmi nella creazione della nuova documentazione.
  2. Vai alla directory principale del progetto.
  3. Crea e attiva un ambiente virtuale Python 3
virtualenv -p python3 
source  / bin / activ
Qui ho chiamato il mio ambiente virtuale

4. Installare tutti i requisiti del progetto

pip install -r Requisiti.txt

Nota: Sphinx e Rinohtype sono già all'interno del file requisito.txt. Se desideri installarli nell'ambiente virtuale del progetto su cui stai lavorando, utilizza i seguenti comandi.

pip installa Sphinx
pip installa rinohtype

5. Creare una directory di documenti e cd in questa directory.

documenti mkdir
documenti cd

6. Setup Sphinx

sfinge-QuickStart
Segui questa configurazione per ora. Puoi riconfigurarlo in seguito da solo.continuazione della foto precedente

7. Open source / conf.py

  • Configurare il percorso alla directory principale
Linee di commento 15–17Cambia percorso in

Il percorso dovrebbe puntare alla directory principale del progetto e guardando la struttura del progetto, da conf.py dovremmo raggiungere la radice salendo due directory principali.

Struttura del progetto
  • Aggiungi Rinohtype all'elenco di estensioni
'Rinoh.frontend.sphinx'
  • Rimuovi il commento dagli elementi in lattice
commentare questiÈ possibile modificare ulteriormente il formato, questi sono solo i valori predefiniti.

8. Aprire index.rst e modificare il contenuto in quanto segue. (Fare clic sul collegamento index.rst per il contenuto completo)

Documentazione per il codice
**************************
.. toctree ::
   : profondità massima: 2
   : didascalia: contenuto:

Docente API principale
===================
.. automodule :: app
   :membri:

Controller TeacherAPI
=====================
.. automodule :: teacherAPI.controller
   :membri:

Modelli TeacherAPI
=================
.. automodule :: teacherAPI.models
   :membri:

Database TeacherAPI
===================
.. automodule :: teacherAPI.database
   :membri:

Insegnante API popolato
===================
.. automodule :: teacherAPI.populate
   :membri:

9. Creare i file di documentazione HTML e PDF.

  • Sempre all'interno della directory di documenti eseguita
fare html
sphinx-build -b rinoh source _build / rinoh

MODIFICA NOTA [16 marzo 2019]: la creazione del file pdf non andrebbe a buon fine se la tua versione di Python è ≥3.7.0 (riferimento al problema con Github)

La prima riga produrrebbe il file HTML in docs / build / html / index.html

Vista di index.htmlVista di index.html

La seconda riga produrrebbe il file PDF in docs / _build / rinoh / SimpleTeacherDataAPI.pdf

Pagina del titolo della documentazioneSommarioPagina di esempio della documentazione

Dopo aver sperimentato la partecipazione a progetti di gruppo, ho iniziato a sviluppare apprezzamento nel documentare il codice e, anche se, non direi che è l'attività più divertente, è sicuramente affidabile e dovrebbe essere praticata dai programmatori .

Per saperne di più su Sphinx:

  • Panoramica - Sphinx 1.8.0+ documentazione

Altri tutorial utili:

  • Documentare il tuo progetto usando Sphinx - Questo mi ha aiutato a capire come documentare il mio codice usando le dotstring di Python.
  • Tutorial sulla Sfinge di Brandon - Tutorial completo sull'uso della Sfinge

Machiels, Brecht. "Rinohtype: The Python Document Processor - Documentazione Rinohtype 0.3.1.Dev0". Rinohtype.readthedocs.io. N.p., 2016. Web. 17 giugno 2018.

Sphinx-doc.org. (2018). Panoramica - Sphinx 1.8.0+ documentazione. [online] Disponibile all'indirizzo: http://www.sphinx-doc.org/en/master/ [consultato il 17 giugno 2018].