Generate Docs 📟

È possibile generare automaticamente la documentazione partendo dalle docstrings (anche queste possono essere auto-inserite) presenti nel codice python. Di seguito una veloce introduzione all'utilizzo

Installazione

Prima di tutto devi assicurarti di aver installato l'ambiente di sviluppo (sevi Dev Env), poi esegui il seguente comando per installare tutto il necessario per creare la documentazione:

make install-doc

Auto Docstrings

Nel Makefile c'è un comando per andare ad inserire in modo automatico le docstrings al codice in formato numpydocs (può essere cambiato, vedi Makefile). Questo avviene grazie ad uno script python che però non funziona benissimo e presenta qualche piccolo problema.

Per andare ad aggiungere in modo automatico le docstrings al codice utilizzare il comando:

make docstrings

IMPORTANTE: assicurati che tutte le funzioni abbiano specificati i tipi per tutti gli argomenti e il tipo di ritorno !!

Verranno creati tanti file .patch. Questi contengono le informazione e le modifiche che devono essere apportate al codice per aggiungere la documentazione.

Una volta ottenuti questi file dovrai applicarli a mano con uno di questi comandi (consiglio di sceglierne uno ed usare sempre quello):

# metodo 1
git apply file.py.patch

# metodo 2
patch -p1 < file.py.patch

Nota: non devi per forza applicarli tutti, puoi sceglierne anche solo alcuni !

Una volta completata questa procedura esegui il comando

make clean-docstrings

per rimuovere tutti questi file ormai inutili.

Un esempio di una funzione prima e dopo la generazione delle docstring:

# prima 
def myfunc(A: np.ndarray, i: bool = True, n: float) -> csr_matrix:
    l = A.shape
    ...

# dopo
def myfunc(A: np.ndarray, i: bool = True, n: float) -> csr_matrix:
    """

    Parameters
    ----------
    A: np.ndarray :
    
    i: bool :
         (Default value = True)

    n: float: 

    Returns
    -------
    """
    l = A.shape
    ...

Docstring Issue

La scelta di utilizzare questo sistema di patch è per aggirare un problema dello script che applica le docstrings in automatico. Questo può anche applicare direttamente le modifiche ai file senza generare i file .patch ma potrebbe succedere che, quando una funzione ha le docstring e viene riavviata la procedura di inserimento, gli argomenti della funzione vengono raddoppiati (vengono reinseriti nella docstring). Più volte si esegue questa operazione più volte verranno duplicati gli argomenti.

La scelta di utilizzare i file .patch è ben ovvia, in questo modo è possibile scegliere solo quali modifiche andare ad applicare e quindi evitare di avere docstrings duplicate qualora il comando venga avviato più volte.

Nota: è possibile modificare i file .patch ma molto spesso i cambiamenti risultano in un file corrotto e non applicabile. Non è stato trovato un metodo efficace per modificarle.

Popolare le Docstrings

Una volta generate in automatico le docstrings queste vanno riempite con la documentazione! Di seguito un esempio di come fare:

def myfunc(a: float, b: float = 3) -> float:
    """Sum 2 float numbers

    Parameters
    ----------
    a: float :
        first number
    b: bool :
        second number
         (Default value = 3)

    Returns
    -------
    res: float: result
    """
    res = a + b
    return res

Riassumendo, devi popolare:

• La descrizione della funzione, il testo deve iniziare attaccato ai doppi apici
• Tutte le descrizioni dei parametri, ti verrà già inserita la tabbatura dove andare and inserire il testo
• Il risultato, che può essere come in questo caso una variabile o soltanto il tipo di ritorno (qualora fosse stato return a +b)

Nota: il Default value è spostato di uno spazio dall'inizio la descrizione del metodo !

Auto Documentazione

Una volta create e popolate le docstrings puoi avviare il processo di creazione automatica della documentazione con il comando:

make docs

Questo popolerà la cartella doc/ con tutti i file necessari per la documentazione.

Nota: ogni volta che avvii questo comando la documentazione precedente viene rimossa ! Nota: puoi inserire anche latex all'interno delle docstring e questo verrà automaticamente renderizzato ! Per saperne di più vedi Makefile

Un esempio di LaTex all'interno delle docstrings:

def myfunc(a: float, b: float = 3) -> float:
    """Sum 2 float numbers
    \\(res = a + b\\)
    Parameters
    ----------
    a: float :
    

Ricordati di eseguire l'escape del carattere \ ogni volta che lo trovi, altrimenti il LaTex non verrà renderizzato bene.