{{tag>dev python framework sphinx flask documentation}}


====== Intégrer une documentation générée par Sphinx à l'application Flask ======

:TODO:

[[dev:python:sphinx:introduction|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 pour 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 :

<code bash>
pip install sphinx sphinx_rtd_theme
</code>

A la racine du projet, exécuter le script **sphinx-quickstart** :
<code bash>
sphinx-quickstart
</code>

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 :
<code bash>
rmdir build/
</code>

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" :

<code bash>
mv source docs
</code>

Dans le fichier ''Makefile'' à la racine du projet, modifier les valeurs des variables **SOURCEDIR** et **BUILDDIR** :

<file>
SOURCEDIR     = docs
BUILDDIR      = app/static/docs

</file>

On peut maintenant générer la documentation depuis la racine du projet :

<code bash>
make html
</code>



===== Références =====

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