Olivier Web Garden

Tout faire avec linux...

Accueil > Articles > Fiches pratiques > Sphinx

Sphinx

Sphinx #1

samedi 23 mai 2020, par Olivier K.

Faire de la documentation de code. C’est indispensable pour comprendre le code d’une application longtemps après, même pour celui qui l’a écrit. C’est une opération qui peut être réalisée dès le départ, même avant la publication officielle, avec un outil comme Sphinx.

Installation

Installer sphinx est simple, il s’agit d’installer un module python
Dans un terminal, taper : python -m pip install sphinx

Version installée : Sphinx v3.0.3

Initialisation

Ensuite, aller à la racine du projet à documenter et créer le répertoire docs.
Ex. pour un projet qui s’appellerait Odysseus et serait développé en python sous KDevelop (voir KDevelop-python et pygame). A partir du répertoire courant de l’utilisateur, dans un terminal, taper :

cd projects/odysseus
mkdir docs

Une fois dans le répertoire, taper la commande : sphinx-quickstart et répondre aux questions posées.

Arborescence du projet exemple

Pour comprendre toutes les manipulations présentées, un point sur l’arborescence :

odysseus (racine projet)
|__config/
|__data/
|__docs/ <= VOUS ÊTES ICI !
|__src/*.py <= code source à documenter
|_README
|_Changelog

Utiliser Markdown

Markdown en plus ou à la place de reStructuredText.
Encore une fois, c’est assez simple. Il faut au minimum la version 0.5 du module recommonmark.

Dans un terminal, taper : python -m pip install --upgrade recommonmark
Pour la configuration voir le chapitre suivant.

Configuration de sphinx : conf.py

Si vous avez opté pour un répertoire de build séparé du répertoire source, alors aller dans le répertoire source pour éditer le fichier conf.py.

Décommenter et modifier

import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))

src est le répertoire où se trouve le code source python.

Ajouter les extensions

extensions = [
   'sphinx.ext.autodoc',
   'recommonmark'
]

Pour avoir la documentation générée à partir des docstrings des modules (sphinx.ext.autodoc) et la possibilité d’utiliser markdown (recommonmark)

Apprendre reStructuredText /Markdown

Ce sont deux langages de balisage de fichiers écrits en mode texte.

reStructuredText

Markdown

Docstrings

Très important. Pour bénéficier de la magie de l’autodoc et générer automatiquement une grande partie de la documentation avec sphinx, il faut, coté code source, commenter son code avec les conventions doctrings.

https://www.python.org/dev/peps/pep...

Résultat généré automatiquement :

make html

Permet de générer la documentation sous forme de pages html statiques. Pour le consulter, il suffit de lire le fichier index.html produit dans le répertoire docs/build/html/ dans un navigateur.

olivier@olivier-All-Series:~/projects/odysseus/docs$ make html

À chaque mise à jour du code source ou des pages du site statique de documentation, il faut faire un make html pour mettre à jour la publication de la documentation.

Sphinx permet d’autres formats de publications (pdf notamment) qui ne seront pas abordés dans cet article.

sphinx-apidoc

Générer toute la documentation du code source en une seule fois : sphinx-apidoc -o ../docs/source ../src/

Cela génère des fichiers .rst pour l’ensemble des modules du programme, ainsi qu’une arborescence particulière, modules.rst, qui contient lui même l’arborescence des modules.

src
===

.. toctree::
  :maxdepth: 4

  cardgame
  characters
  game
  main
  player
  pygame_board
  pygame_endgame
  pygame_init
  pygame_menu

Ce fichier peut être modifié à volonté (notamment l’ordre des pages, le titre), il ne sera pas régénéré par une prochaine commande sphinx-apidoc sauf si suppression au préalable ou passage de l’option -f.

Pour pouvoir ajouter la documentation de nouveaux fichiers pythons : il faut utiliser la même commande (sphinx-apidoc -o ../docs/source ../src/) le code déjà existant sera préservé.

Pour régénérer complètement la documentation : ajouter l’option -f qui écrasera toutes les pages, y compris la page modules.rst.

Peut-on générer totalement la documentation en markdown ?

Oui, avec la commande sphinx-apidoc -s md -o ../docs/source ../src/.
Par contre, il faudra un fichier index.rst, modules.md généré par cette commande ne sera pas fonctionnel : il faudra le renommer modules.rst.

Pour vraiment tout faire en markdown, il faut utiliser un autre outil que sphinx.

index.rst

Ce fichier est généré lors du passage de la commande sphinx-quickstart, il gère le contenu de la page index.html qui sera générée (ou première page du pdf).

.. Odysseus documentation master file, created by
  sphinx-quickstart on Fri May 22 18:40:07 2020.
  You can adapt this file completely to your liking, but it should at least
  contain the root `toctree` directive.

Welcome to Odysseus's documentation!
====================================

.. toctree::
  :maxdepth: 2
  :caption: Contents:

  modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

toctree concerne la partie navigation. Il faut ajouter modules qui fait référence au fichier modules.rst généré par la commande sphinx-apidoc.

Changer de thème

Installer le thème Read the doc à la place du thème par défaut alabaster.

  1. Charger le thème avec pip : python -m pip install sphinx_rtd_theme
  2. Modifier le fichier conf.py : html_theme = 'alabaster' devient html_theme = 'sphinx_rtd_theme'
  3. make html

Un changement de look ultra rapide...

conf.py

Le fichier conf.py avec tous les réglages proposés dans cet article :

Les modifications apportées ont été signalées avec des commentaires commençants par # !!

Sources documentaires


Voir en ligne : https://www.sphinx-doc.org