Sphinx permet de générer de la documentation dans différents formats. Ici on souhaite produire de la documentation au format HTML et la servir via l'application Flask.

Pour que Flask soit en mesure de servir les fichiers, on configurera Sphinx qu'il génère les fichiers de documentation dans un sous-répertoire du dossier ./static de l'application Flask.

Activer l'environnement virtuel et télécharger les paquetages de l'application Sphinx :

pip install sphinx sphinx_rtd_theme

A la racine du projet, exécuter le script sphinx-quickstart :

sphinx-quickstart

Le script fonctionne en mode interactif et propose de choisir des options :

• A la question “Séparer les répertoires source et de sortie” réponse “y”

Le script initialise l'arborescence nécessaire au bon fonctionnement de Sphinx notamment les dossiers source et build.

Dans notre cas le dossier par défaut ./build ne sera pas utilisé, on le supprime :

rmdir build/

Sphinx crée par défaut un dossier nommé “source” pour regrouper les fichiers sources permettant de produire la documentation. Pour éviter toute confusion avec les sources de l'application Flask, on préfère ici le renommer “docs” :

mv source docs

Dans le fichier Makefile à la racine du projet, modifier la valeur des variables SOURCEDIR et BUILDDIR :

SOURCEDIR     = docs
BUILDDIR      = app/static/docs

Générer la documentation depuis la racine du projet :

make html

• https://stackoverflow.com/questions/14912787/sphinx-documentation-inside-a-flask-running-web-application