Créer des documents de cours agiles avec Sphinx

Auteur : Philippe Dessus, Espé & LSE, Univ. Grenoble Alpes.

Date de création : Avril 2016.

Date de modification : 18 mai 2017.

Projet : Projet Idefi ReFlexPro

Statut du document : En travaux.

Licence : Document placé sous licence Creative Commons : BY-NC-SA http://creativecommons.org/licenses/by-nc-sa/3.0/fr/.

Résumé : Cet ensemble de document décrit l’utilisation de l’outil générateur de documentations Sphinx et de ses extensions, et explique en quoi l’outil peut être utile à des fins de formation

L’existant

Il existe de nombreux logiciels de conception de cours à distance ou hybride. Ils comprennent des Learning Management Systems, comme Moodle, Blackboard, Chamilo, etc., ou des outils d’édition de documents, comme Scénari (nommés “chaîne éditoriale”).

Les outils de plate-forme sont assez lourds à gérer, authentification, modularité réduite, nécessité de reprendre le cours d’une année à l’autre..., et surtout fermés.

Les LMS

Les chaînes éditoriales

Une chaîne éditoriale est un

Scénari est plus souple, mais nécessite des ressources assez importantes.

Sphinx est un outil initialement conçu pour générer les docs. du langage Python, ses nombreuses extensions et possibilités le rendent intéressant d’utilisation dans des formations.

Les fonctionnalités

  • Séparation forte données/forme, ce qui rend très facile le changement de thème.
  • Codage du texte en ResT, nécessitant peu de ressources
  • Peut faire l’objet de partage de documents collaboratives.
  • De nombreuses extensions (BibTeX pour les références, hieroglyph pour les présentations, Graphviz pour les graphiques, etc.)
  • La configuration des fichiers se règle entièrement par un fichier, conf.py, ce qui permet d’avoir une config stable et réplicable entre projets et réadaptable selon les besoins;

Cycle de tâches d’un concepteur de cours dans Sphinx

Faire des cours implique produire des présentations (simplifiées) et des notes de cours (plus complètes) et oblige à gérer des formats de fichiers différents, donc perte de temps à gérer des versions et des formats. De plus, il est souvent nécessaire d’adapter ses cours selon les niveaux des étudiants auxquels on s’adresse. Enfin, il peut être intéressant de produire son cours sur différents formats (e.g., PDF, HTML), voire de pouvoir les éditer collaborativement.

Ces différentes contraintes sont assez difficiles à concilier. En effet, il existe des outils de conception de cours de haut niveau (e.g., comme Scenari), mais ils sont très fermés et les documents créés avec ce logiciel ne peuvent aisément être récupérés d’une autre manière. Les outils de plus bas niveau (traitements de texte), assez souvent, ne disposent pas de fonctionnalités de codage du contenu.

Nous présentons ici quelques fonctionnalités intéressantes de Sphinx, un logiciel conçu initialement pour la documentation du langage Python.

Limites

Installation Windows délicate

Contextes d’utilisation

Doc. modulables, travail sur briques réutilisables au besoin (intégrer des diapos aux documents); Maintenance facilitée Système tout en un

Maths: interface avec LaTeX

Indices and tables