MkDocs vs Sphinx

Estimated time to read: 1 minute

Nel panorama delle librerie per generare documentazione automatica e siti statici non possiamo non citare Sphinx che forse ha rappresentato lo standard python fino a qualche anno fa.

Potete trovare già un riferimento a sphinx e alle sue caratteristiche all'interno di questo articolo

In questa sezione confrontiamo invece in maniera schematica quali sono le caratteristiche di sphinx e mkdocs in modo da poter evidenziare i punti di forza di entrambi.

	MkDocs	Sphinx
Formati supportati	Markdown	rST ma con l'estensione myst-parser supporta il markdown
Startup	Facile con il comando poetry run mkdocs .	Semplice con il comando sphinx-quickstart
Configurazione	Utilizza un file yaml mkdocs.yml	Utilizza un file python conf.py
Layout	Elegante ed accattivante, risulta anche ben navigabile	Risulta un po' retro. Iconico il tema Read the Docs
Build	Fornisce un server locale per provare interamente il sito. Comodo il comando poetry run mkdocs serve	Genera la build del sito ma é l'utente che lo deve poi provare nel suo browser. Questa operazione viene fatta con make html
Estensioni	Sono tantissime ma non tutte vengono mantenute	Sono presenti molte estensioni ma la community é meno attiva rispetto a mkdocs
Personalizzazione	Possibilità infinite grazie all'integrazione dei css e ai temi disponibili	Decisamente meno personalizzabile
Integrazione con terze parti	Integrazione con Confluence con questa estensione	Integrazione con Confluence con questa estensione