Python, documentation et Sphinx
Lorsqu’on utilise un projet ou une bibliothèque, il est souvent agréable de générer la documentation localement, plusieurs raisons à ça.
- Temps de réaction aux chargement de pages plus rapide.
- Pas besoin de connexion Internet pour consulter la documentation, pouvant être utile à certain (train, déplacement, Internet coupé par Hadœpi…)
- Pas de « mince le site est down… »
- Pour les petit projet, la documentation sur le site ne correspond pas forcément à l’actuel car le développeur ne prend pas forcément le temps de mettre à jour.
Par chance, les projets basé sur Python utilises presque tous un même outil pour générer la documentation, Sphinx. Consistant à parser des fichiers en ReStructuredText (extention .rst).
Pour Arch Linux, Sphinx est disponible dans [community], il est également disponible pour Ubuntu et Debian, et très certainement pour toutes autres distributions.
apt-get install python-sphinx
Le fonctionnement de sphinx est simple, un utilitaire règle les détails en
écrivant un fichier Makefile, pour lequel il suffira d’utiliser avec un make.
Par exemple, prenons lettuce comme projet, dont j’en faisais la présentation dans un billet précédent
$ cd lettuce/docs
$ make html
rm -rf _build/*
sphinx-build -b html -d _build/doctrees . _build/html
Making output directory...
Running Sphinx v1.0.7
loading pickled environment... not yet created
building [html]: targets for 17 source files that are out of date
updating environment: 17 added, 0 changed, 0 removed
reading sources... [100%] tutorial/tables
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/nicolas/test/lettuce/docs/tutorial/django.rst::
WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] tutorial/tables
writing additional files... genindex search
copying images... [100%] tutorial/flow.png
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 1 warning.
Build finished. The HTML pages are in _build/html.
Comme indiqué, le résultat se trouve dans _build/html dont il suffit de
lancer index.html.
Il est donc possible de générer rapidement la documentation avec un simple :
D’autre format sont supporté, notamment le PDF. Cette opération passe par la génération d’un document LaTeX.
make latexpdf
Pour générer le fichier Makefile, Sphinx fournit un utilitaire en ligne de commande, permettant, une fois quelques questions basique répondu, de générer le Makefile. Heureusement les questions sont assez simple, et les valeurs par défaut sont souvent suffisante.
Ce billet est une très courte introduction de ce que Sphinx peut faire. Cet outil vaut à être connu.
