Documentare il codice
Estimated time to read: 2 minutes
Come abbiamo visto mkdocs è molto comodo e veloce, una delle funzionalità più utilizzate della libreria è per commentare e condividere velocemente documentazione tecnica relativa al codice.
Per farlo è necessario utilizzare una particolare estensione chiamata mkdocstring.
Questa estensione consente di creare automaticamente la documentazione delle funzioni e delle classi Python, riuscendo a leggedere le notazioni e le docstring trasformandole in codice HTML.
Attenzione nell'installazione della libreria che si chiama: mkdocstrings-python e non solamente mkdocstrings, dovete quindi fare con poetry:
poetry add mkdocstrings-python
La differenza è che mkdocstrings-python è l'handler per supportare il codice python.
Con mkdocstrings è anche possibile documentare e supportare codice shell installando: mkdocstrings-shell
Una volta installata la libreria sarà necessario anche configurarla, per farlo è importante inserire nel mkdocs.yaml file all'interno della sezione plugins questa configurazione
- mkdocstrings: default_handler: python handlers: python: options: show_source: true show_root_heading: yes heading_level: 0 filters: - '!^_' # exclude all members starting with _ - '!^__init__$' # exclude __init__ modules and methods Per farlo prova a creare una funzione, ad esempio:
def sum_numbers(num1: int, num2: int) -> int: ``` def sum_numbers(num1: int, num2: int) -> int: """Sum 2 int numbers and obtain a result Args: num1 (int): the first number you want to sum num2 (int): the second number you want to sum Returns: result (int): the sum of the two numbers """ return num1 + num2 Dopodiche dovrai importare il package all'interno di un file markdown utilizzando una speciale notazione, supponiamo che il tuo codice sia nella seguente cartella (o modulo): myapp/test/utils.py
All'interno di un file markdown dovrai scrivere:
In automatico mkdocstring visualizzerà all'interno del sito il tuo esempio.
Ovviamente consigliamo sempre di provare a modificare i file markdown e di controllare sempre il risultato, potete sempre fare in modo di aggiungere altri commenti o abbellimenti in markdown normalmente.