Sphinx
Présentation
Sphinx est un outil de génération de documentation automatique utilisant le format ReStructured Text. Après une phase de configuration, il permet de générer assez facilement la documentation d'un projet python en un format pdf ou html.
Voici un petit tutoriel vous permettant pas a pas de créer votre propre documentation. La documentation officielle de Sphinx est disponible a cette adresse : http://sphinx.pocoo.org/
Configuration
Création du projet
Pour créer la documentation du projet, on utilisera le script d'installation sphinx-quickstart.
Ce script vous posera plusieurs questions afin de réaliser automatiquement la configuration qu'il convient. Il est important de bien répondre a certaines questions pour ne plus avoir a modifier a la main le fichier de configuration ensuite.
Remarque :
Notez qu'a chaque question, une valeur est entre crochets, il s'agit de la valeur par défaut qui sera fixée si vous pressez Entrée.
Chemin de destination
Enter the root path for documentation.> Root path for the documentation [.]:
Il s'agit du chemin ou vous souhaitez créer les fichier de documentation. Si vous mettez le chemin d'un endroit qui n'existe pas, il sera crée automatiquement.
Séparation source/génération
You have two options for placing the build directory for Sphinx output.Either, you use a directory "_build" within the root path, or you separate"source" and "build" directories within the root path.> Separate source and build directories (y/N) [n]:
Cette étape précise si les fichier reStructured Text et les fichiers de documentation générés se trouveront au même endroit ou dans des répertoires séparés. Pour plus de clarté, je vous recommande d'opter pour les fichiers séparés.
Préfixe des dossiers de styles
Inside the root directory, two more directories will be created; "_templates"for custom HTML templates and "_static" for custom stylesheets and other staticfiles. You can enter another prefix (such as ".") to replace the underscore.> Name prefix for templates and static dir [_]:
Ici on vous demande de choisir un préfixe pour les dossiers qui vont contenir les styles. Peu d'intérêt pour nous, laissez la valeur par défaut.
Titre et auteur
The project name will occur in several places in the built documentation.> Project name: CheVal> Author name(s): Maxime Le Coz <lecoz@irit.fr>
Il s'agit ici d'entrer les champs de titre du projet et le nom de l'auteur (avec éventuellement un mail de contact). Soyez imaginatifs !
Numéro de version
Sphinx has the notion of a "version" and a "release" for thesoftware. Each version can have multiple releases. For example, forPython the version is something like 2.5 or 3.0, while the release issomething like 2.5.1 or 3.0a1. If you don't need this dual structure,just set both to the same value.> Project version: 0> Project release [1]:1
Ici on vous demande le numéro de version du projet.
L'usage en matière de numérotation de version, est de suivre la forme version.release. L'augmentation du numéro de version indiquant un changement majeur par rapport a la version précédente. Le numéro de release se rapportant plutôt a des changements mineurs.
Extension des fichiers ReStructured Text
The file name suffix for source files. Commonly, this is either ".txt"or ".rst". Only files with this suffix are considered documents.> Source file suffix [.rst]:
Ceci correspond a l'extension que vous donnerez aux fichier ReStructured Text, laissez la valeur par défaut.
Nom du fichier de documentation principal
One document is special in that it is considered the top node of the"contents tree", that is, it is the root of the hierarchical structureof the documents. Normally, this is "index", but if your "index"document is a custom template, you can also set this to another filename.> Name of your master document (without suffix) [index]:
Cette option sert a changer le nom par défaut du fichier de sorti de documentation. Laissez-le par défaut.
Format ePub
Sphinx can also add configuration for epub output:> Do you want to use the epub builder (y/N) [n]:
Permet de gérer le format ePub, un format ouvert pour les publications électroniques. Nous n'en avons pas l'utilité ici, laissez n.
Plugins Additionnels
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]:
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
> viewcode: include links to the source code of documented Python objects (y/N) [n]:
Sphinx vous propose ici d'activer ou non tout une liste de plugins complémentaires plus ou moins utiles.
autodoc : Il vous faut impérativement activer ce plugin, c'est lui qui active la fonctionnalité de parcours automatique du code pour générer la documentation du module.
doctest : Permet d'exécuter du code dans les commentaire afin notamment de générer des exemples.
intersphinx : Permet de faire le lien entre plusieurs documentations Sphinx.
todo : Permet d'utiliser la balise
todopour afficher dans la documentation la liste des choses qu'il reste a faire.coverage : Permet des calculs statistiques sur le taux de commentaire.
pngmath et mathjax : Permet d'écrire des formules mathématiques pour les inclure dans la documentation sous forme d'image.
ifconfig : Permet d'inclure ou non des partie de documentation selon des valeurs de configuration.
viewcode : Permet d'afficher la partie du code correspondant a la documentation.
Scripts automatiques
A Makefile and a Windows command file can be generated for you so that youonly have to run e.g. `make html' instead of invoking sphinx-builddirectly.> Create Makefile? (Y/n) [y]: > Create Windows command file? (Y/n) [y]:
Permet la création de script automatique de génération de la documentation pour unix et windows.
Configurations supplémentaires
Une fois sphinx-quickstart terminé, le fichier conf.py est généré a l'endroit que vous avez indiqué comme racine des sources de la documentation.
Vous y retrouverez toutes les informations que vous avez entrée via le script. Néanmoins une petite modification s'impose pour préciser a Sphinx où se trouve le module que vous avez créé et dont vous souhaitez créer la documentation.
Pour cela, localisez la ligne suivante :
# sys.path.insert(0, os.path.abspath('.'))
et remplacez la par :
sys.path.insert(0, os.path.abspath('<Dossier contenant votre module>'))
Une fois ceci terminé, la configuration ne devrait plus avoir besoin d'être modifiée par la suite. Je vous invite cependant à regarder les différentes valeurs utilisées dans la partie configuration HTML qui vous permettrons de personnaliser l'affichage de votre documentation.
Vous pouvez notamment modifier la valeur de pour l'une des valeurs de cette page, pour modifier toute l'apparence de la documentation.
La configuration automatique aura également généré un fichier index.rst au même endroit, il s'agit du fichier ReStructured Text qui définira la structure de votre documentation.
Génération
Pour générer la documentation, vous pouvez soit utiliser les scripts rapides si vous les avez générés (par exemple en faisant make html), soit en utilisant la commande sphinx-build -b html source/ sortie/
