Outils pour utilisateurs
Ceci est une ancienne révision du document !
−Table des matières
sphinx : Générateur de documentation
Sphinx est un programme dédié à la génération de tous types de documentation associée à un projet:
- La documentation de référence (documentation des modules, classes et APIs);
- les tutoriaux (documentation à objectifs pédagogiques);
- Les How-To (documentation ayant pour objet la résolution de problèmes);
- Les documents explicatifs ayant pour objectif de faire connaître ou de justifier certains choix.
Souvent on pense à Sphinx comme à un outil de génération de documentation technique pour Python capable d'extraire les docstrings du code afin de produire une documentation de référence en HTML.
Plus généralement Sphinx peut prendre en entrée tout type de document texte et produire une sortie lisible.
En général les fichiers texte en entrées utilisent le formatage reStructredText et la sortie produite par Sphinx est un ensemble de documents formatés en HTML.
Sphinx propose d'autres types de sorties comme PDF, ePub, man etc.
Sphinx a besoin d'un fichier de configuration (conf.py)
Sphinx est modulaire, il comporte de nombreuses extensions facilement activables.
Auto-documenter un package Python
Sphinx a été conçu par la communauté Python pour les projets Python. Cependnt il est utilisés par de nombreux autres projets opensource.
Sphinx utilise l'extension autodoc pour inclure les docstrings dans la documentation à produire.
reStructuredText est le formatage utilisé par défaut mais d'autre formatages peuvent être utilisés comme Markdown mais dans ce cas des extensions supplémentaires seront nécessaires.
Pour documenter l'ensemble des classes d'un module:
- Le fichier conf.py doit avoir l'extension autodoc (
sphinx.ext.autodoc) déclarée; - Le fichier RST doit utiliser la directive automodule avec l'option
:members:
.. automodule:: my_module_name :members:
L'extension doctest
sphinx.ext.doctest
Références
Outils de la page
