Nicolas Friedli

consultant web indépendant

Outils pour utilisateurs

Outils du site


sites-statiques:sphinx:start

Sphinx

Sphinx est un générateur de site statique conçu pour une documentation. Il est prévu pour produire d’autres documents que des sites HTML, par exemple des livres complets en pdf.

Balisage en reStructuredText

Alors que beaucoup de sites statiques sont créés en formatant le contenu en markdown, Sphinx utilise (historiquement) rST (reStructuredText). C’est un langage de balisage léger beaucoup plus riche que markdown. Il est aussi plus complexe.

Aujourd’hui, Sphinx permet l’utilisation de markdown, dans une version particulière pour conserver la richesse de l’outil. Je ne suis pas convaincu, mais comprends le choix de l’équipe de développement.

De plus, Sphinx enrichit le rST de base par des directives. Il est ainsi possible de créer des encarts, des renvois, des index, etc. sans code.

Structure par toctree

La plus grande particularité de Sphinx, c’est la hiérarchisation du site par une directive: toctree. Ainsi, il est possible d’obtenir une structure absolument conforme à la hiérarchie des fichiers sources, comme une structure complètement différente.

C’est dans les pages elles-mêmes que se choisir la manière d’organiser le contenu. Une page mère «décide» de quelles seront ses page filles (et dans quel ordre) directement dans le balisage léger en rST. C’est déconcertant mais très puissant.

Des liens partout

Sphinx étant conçu pour documenter, il permet de renvoyer à tout de manière limpide. Un liens peut renvoyer à une autre page, à un sous-titre de page, à une entrée de glossaire, à un paragraphe précis, etc.

L’outil pousse au maximum la logique de la non répétition (Don’t repeat yourself ou DRY). Dès qu’un contenu existe, mieux vaut y renvoyer que le copier ailleurs. Tout est pensé pour simplifier la maintenance dans la durée.

Un originalité de Sphinx: la possibilité d’intégrer à la fois des liens vers des pages et des tables des manières de ces pages dans un même menu. Ainsi, dans la navigation, les internautes n’ont pas à se demander si la navigation a lieu dans une page ou d’une page à l’autre. Génial pour de la documentation.

Des outils intégrés

Lors de la compilation, Sphinx intègre plusieurs outils intéressant. Par exemple le contrôle automatique des liens internes et externes (make linkcheck), la compilation de toute la documentation en un seul document (make singlehtml) ou en plusieurs (make dirhtml), etc.

Il vaut la peine de consulter les sources de sites comme Write the Docs ou Diátaxis Framework pour mesurer l’efficacité de de Sphinx.

sites-statiques/sphinx/start.txt · Dernière modification: 04.05.2022 par Nicolas Friedli