J’ai dirigé la documentation Sphinx dans plusieurs entreprises, pour plus de 100 services différents au total. Le site de documentation de Sphinx est depuis des années mon ouvrage de référence, et TechWriters.ru a également utilisé ce moteur jusqu’en août 2026. toctree, include, rôles, domaines, thèmes et avertissements de build viennent de projets réels.
Cette expérience explique le sujet, pas la note. Le portail et le dépôt ont été évalués comme un produit documentaire : prise en main, structure, référence, exemples, réutilisation, build, recherche, versions, interface et traduction.
Périmètre de l’étude
Instantané du 17 août 2026 sur le site master et le dossier doc/ du dépôt officiel au commit e44a40e. Les comptes viennent des sources et l’évaluation éditoriale des pages publiées.
fichiers .rst avec l’historique
fichiers .rst hors changes/
mots et jetons selon wc -w
extensions intégrées activées
types de builder documentés
Un projet compact couvre un produit immense
Le corpus couvre démarrage, guide utilisateur, développement d’extensions, API Sphinx, commandes, configuration, formats, FAQ et historique complet.
| Besoin | Section | Résultat |
|---|---|---|
| Démarrer | Getting started et tutoriel complet | Orientation courte et projet guidé avec narration et API. [S2] |
| Utiliser | reStructuredText, Markdown, liens, configuration, builders, domaines | Manuel complet jusqu’à l’internationalisation. [S3] |
| Étendre | Tutoriels, procédures et API | Rôles, directives, événements, domaines, parseurs, thèmes et tests. [G3] |
| Maintenir | Communauté, contribution, releases et FAQ | Vie du projet et réponses accumulées à nettoyer. [S11] |
| Consulter | Commandes, conf.py, extensions, glossaire, changelog | Une profondeur de référence remarquable. [S1] |
Les développeurs utilisent Sphinx comme banc d’essai
La configuration illustre presque tout l’arsenal caractéristique.
Structure
[G3]35 toctree relient les documents et l’accueil sépare quatre familles.
Réutilisation
[S4]Des include et 31 literalinclude lisent de vrais fichiers Python.
API depuis le code
[G2]autodoc et autosummary sont actifs avec 13 automodule, 75 autoclass et 18 autofunction.
Liens externes
[S9]intersphinx relie Python, Requests et Read the Docs.
Diagrammes
[G2]Graphviz et les diagrammes d’héritage montrent phases, événements et classes.
Versions
[S12]612 versionadded, 252 versionchanged et 18 deprecated accompagnent l’API.
Formats
[S6]21 builders sont documentés, avec HTML, PDF, ePub, man et Texinfo.
Validation
[G2]nitpicky, coverage, types d’avertissement et linkcheck font du build un contrôle qualité.
La réutilisation fait la force de reStructuredText
Une section commune peut entrer dans plusieurs guides, être limitée par des marqueurs et varier selon le builder. literalinclude, only, rst_prolog et rst_epilog complètent le modèle.
include
Insère un fragment .rst partagé ou une section marquée.
literalinclude
Lit le code depuis un vrai fichier et évite les divergences.
only
Fait varier le contenu selon builder ou tag.
rst_prolog et rst_epilog
Ajoutent définitions et inclusions globales.
Une section, deux guides
.. include:: _shared/security-note.rst
:start-after: .. security-start
:end-before: .. security-end_shared/security-note.rst reste la source unique et les deux pages reçoivent la même correction.
Note éditoriale : 78 sur 100
Référence, réutilisation et ingénierie obtiennent le maximum. Interface et traduction pénalisent le résultat.
78/100
Le parcours est logique, mais commence deux fois
L’accueil sépare bien démarrage, guide, communauté et référence. Getting started et Build your first project se chevauchent sans distinguer assez clairement le parcours rapide du tutoriel complet.
| Observation | Preuve | Jugement |
|---|---|---|
| Carte solide | Quatre groupes révèlent le type de contenu. | L’architecture se lit immédiatement. [S1] |
| Tutoriel pratique | Une bibliothèque fictive relie narration et API. | Un exemple continu enseigne mieux. [S2] |
| Deux entrées | Les bases sont partiellement répétées. | Nommer explicitement parcours rapide et tutoriel complet. [S1] |
| Fin inachevée | Quickstart finit par More topics to be covered. | Un résidu de brouillon affaiblit la page. [S1] |
| Révision inégale | L’accueil conserve Add documentation translations multiple languages. | Une préposition manque sur la vitrine. [S1] |
| FAQ vieillissante | Epydoc, SCons, ancien hébergement PyPI et _gaq subsistent. | Séparer l’historique du dépannage actuel. [S11] |
L’interface montre l’âge du projet
Navigation, recherche, index, source et versions fonctionnent. Le thème sphinx13 reste dense et le panneau sombre Read the Docs semble ajouté par-dessus le site.
Fonctionne
Arbre, ancres, index, recherche, source et versions.
Vieillit
Typographie dense, petits liens, colonne chargée et panneau RTD séparé.
Trompe
Le russe, l’allemand et le français ont été vérifiés : aucun n’est complet. Le russe et l’allemand restent presque entièrement anglais ; le français alterne traduction et paragraphes anglais.
Priorité
Afficher la couverture de traduction et moderniser sans perdre la navigation profonde.
Pratiques à reprendre
| Pratique | À reprendre |
|---|---|
| Liens sémantiques | Référencer objets et sections par identifiant. |
| Fragments communs | Réutiliser avertissements et exigences avec include. |
| Exemples vivants | Lire le code testé avec literalinclude. |
| Notes de version | Placer changements et dépréciations près de l’API. |
| Build strict | Vérifier avertissements, liens et références en CI. |
| Plusieurs formats | Produire PDF, man ou ePub depuis la même source. |
| Localisation honnête | Ne pas présenter une traduction partielle comme complète. |
Sources de l’étude
Conclusion : excellente ingénierie dans une vitrine vieillissante
Sphinx se documente presque exemplairement dans ses sources et exploite hiérarchie, réutilisation, liens sémantiques, API générée, diagrammes et sorties multiples.
La faiblesse concerne la lecture : interface ancienne, double démarrage, résidus de brouillon, FAQ historique et sélecteur de langues trop prometteur.
L’attachement demeure. Sphinx offre toujours une combinaison rare de structure, de réutilisation et de discipline de build.
Le portail prouve la puissance de Sphinx tout en montrant comment l’ingénierie peut dépasser la présentation.