{{tag>dev python documentation sphinx}}

===== Sphinx : Installation ======

Sphinx utilise Python et make pour construire la documentation:
<code bash>
sudo apt install build-essential python3 python3-pip python3-venv
</code>

Créer et activer l'environnement virtuel du projet et on installe les modules via pip3. Ici en plus du module sphinx on installe le thème [[https://docs.readthedocs.io|read the docs]]

<code bash>
cd my_app
source app_env/bin/activate
pip3 install sphinx sphinx_rtd_theme
</code>

Le script **sphinx-quickstart** assiste l'utilisateur pour la création de l'arborescence de base de la documentation et son intégration au sein du projet.

Se placer à la racine du projet et lancer la commande **sphinx-quickstart**
<code bash>
sphinx-quickstart
</code>

Ici on fait le choix de séparer les répertoires source et build de la documentation.

Pour plus de clarté, on fait le choix de renommer les répertoires :
  * ''source'' -> ''doc'' : Pour sphinx ''source'' contient les fichiers sources de la documentation mais dans un projet de code, cela peut porter à confusion.
  * On crée un sous repertoire dans build pour la documentation.

Il faudra ensuite modifier le fichier Makefile:

<code bash>
mv source doc
mkdir build/doc
</code>

<code bash>
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = doc
BUILDDIR      = build/doc
</code>

Tester une compilation
<code bash>
make html
</code>

===== Changer le thème =====

Le thème "Read The Doc" a été téléchargé mais il n'est pas encore utilisé. Modifier le fichier de configuration ''**doc/conf.py**'' :

<code python>
...
# Utilise le thème Read the Doc
html_theme = 'sphinx_rtd_theme'
</code>

Les nombreuses [[https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html|options de configuration du thème]] son décrite dans la documentation officielle du thème.

<note>
Pour écrire la documentation dans une autre langue que l'anglais il faut activer l'extension ''sphinx_rtd_theme'' pour permettre la traduction des éléments de l'interface. Modifier le fichier conf.py
</note>

<code python>
...
extensions = [
  'sphinx_rtd_theme',
]
</code>
===== Références =====

  * https://towardsdatascience.com/documenting-python-code-with-sphinx-554e1d6c4f6d?gi=d2b08f5fbc51
  * https://www.sphinx-doc.org/en/master/
  * https://blog.flozz.fr/2020/09/07/introduction-a-sphinx-un-outil-de-documentation-puissant/