Sphinx

Fiche logiciel validé
  • Création ou MAJ importante : 27/04/11
  • Correction mineure : 06/04/13
Mots-clés
Pour aller plus loin

Sphinx : générateur de documentations HTML, LaTeX (PDF), nroff

Description
Fonctionnalités générales

Sphinx permet de produire des fichiers HTML, LaTeX (puis PDF), nroff ou texte brut à partir de fichiers rédigés en reStructuredText.

Il est écrit en Python et certains de ses fichiers de configuration nécessitent la connaissance du langage Python.

Il a été initialement développé pour produire la documentation de Python (en particulier en utilisant le texte brut des docstrings).

Il s'adapte à d'autres types de production (certains ont abandonné LaTeX pour écrire des livres avec Sphinx) .

Il est possible d'insérer des images déjà mises en forme (svg, png, etc.). On peut décrire des graphes directement en langage DOT (Graphviz).

Sphinx produit aussi les tables des matières, des pages d'index et propose une page de recherche dans la sortie HTML. D'autre part, l'arborescence de fichiers HTML produite est autonome, il est possible de faire un tar du répertoire HTML produit et de le déplacer en garantissant toutes les références croisées (liens, images, index...). Certaines structures d'accueil, telle SourceForge autorise la mise à jour de pages HTML en utilisant un tel tar.

On peut choisir le rendu final des pages HTML parmi plusieurs chartes graphiques (thème). Cet aspect est particulièrement soigné.

Avec le mécanisme d'intermapping, il est possible de lier de façon concise (sans URL) des documentations de projets indépendants.

Moins riche sémantiquement et hiérarchiquement que XML/Docbook, reStructuredText a l'avantage d'être plus facilement et plus légèrement insérable dans les codes sources.

Plusieurs langages (Java avec javadoc, matlab ou IDL, etc) ou d'autres outils proposent des services analogues (production de HTML à partir de commentaires structurés).

Dans un contexte de développement multi-langages, Sphinx assure une homogénéité de la documentation projet très appréciable.
En effet la souplesse de sa configuration et sa capacité d'extension permet l'intégration de n'importe quel langage. Il faut cependant noter que, si Sphinx prend en compte les éléments syntaxiques de C,C++ ou Java par exemple, il n'est pas capable d'extraire de la documentation du code source. Il faut donc avoir un générateur de reStructuredText à partir de son code source. Seul le code source Python, en utilisant les docstrings, est automatiquement analysé.

Sphinx est une excellente porte d'entrée de l'approche programmatique de la documentation.

Autres fonctionnalités

Vérificateur de liens hypertextes

Beaucoup de plugins disponibles

Contexte d'utilisation dans mon laboratoire/service

J'utilise Sphinx depuis le printemps 2010 pour produire la documentation de tous mes projets de développement d'applications logicielles (FORTRAN, IDL, octave, shell, perl, XML/XSL, etc) dans le contexte scientifique océanographie et climatologie.

Les sources reStructuredText des manuels sont inclus dans les sources de mes composantes logicielles préfixés par le signe de commentaires dépendant du langage avec un marqueur de début et de fin.

Les sources reStructuredText des guides - décrivants les jeux de données, les procédures, etc.- sont dans des fichiers dédiés.

sphinx-build est utilisée pour la génération de l'ensemble de la documentation projet (guides et manuels).
Cette phase est précédée de l'extraction des parties reStructuredText de chaque source.

Limitations, difficultés, fonctionnalités importantes non couvertes

Des notions de Python sont nécessaires pour adapter le fonctionnement de Sphinx à ses besoins particuliers.

Le reStructuredText de Sphinx est enrichi (directives et rôles) par rapport à celui de docutils donc il peut devenir impossible d'utiliser la suite rst2* ou d'autres outils s'alignant strictement sur la forme canonique pour exploiter ses documents sources.

Pas d'analyse automatique du code source, excepté pour Python.
Pas d'index ou de glossaire inter-projets.
Gestion des tables pas terrible.
Portabilité du texte produit ou des images pas toujours assurée, en particulier pour le PDF (passant par LaTeX).

Environnement du logiciel
Logiciels connexes
Autres logiciels aux fonctionnalités équivalentes
Environnement de développement
Eléments de pérennité
Environnement utilisateur
Liste de diffusion ou de discussion, support et forums

http://groups.google.com/group/sphinx-dev

Très réactive et constructive sans être trop bavarde (moins de 10 mails par jour).

Documentation utilisateur
Divers (astuces, actualités, sécurité)
  • Voir le cours Sphinx de Marc Poinot http://calcul.math.cnrs.fr/spip.php?article164&lan...
    donné lors de ANGD Python en calcul scientifique à Autrans, France du 6 décembre au 10 décembre 2010;

  • Il y a beaucoup de logiciels nommés "Sphinx" donc lors de vos recherches d'information sur la toile ajouter "pocoo" dans la liste de
    mots.

Commentaires

Responsable thématique précédent

Cette fiche a d'abord été suivie par le responsable thématique Loïc Gouarin. Anne Cheylus l'a reprise en avril 2013.