.. include:: inclure_infos.txt

.. TODO
	https://media.readthedocs.org/pdf/sphinxext-survey/latest/sphinxext-survey.pdf
	regarder mail Saul Carliner.
	Content Strategy: An Integrative Literature Review

***********************************************
Créer des documents de cours agiles avec Sphinx
***********************************************
	
* **Auteurs** : |PhD|.

* **Date de création** : Avril 2016.

* **Date de modification** : |today|.

* **Projet** : |projet|

**Statut du document** : En travaux.

**Licence** : |cc|

**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


.. La table des matières de tout le cours est ici:

Table des matières
==================

.. toctree::
	:maxdepth: 1

 	info_cours
 	theorie
 	organisation
 	installer_sphinx
 	syntaxe_rest
 	syntaxe_sphinx
	questionnaires
	construction
	documentation
	outils
	glossaire

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 document, comme Scénari.

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.

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 (p. ex., 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 (comme p. ex. 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

Pour aller plus loin
====================
Répertoire des extensions Sphinx : http://sphinxext-survey.readthedocs.org/en/latest/
Une partie des extensions Sphinx : https://bitbucket.org/birkenfeld/sphinx-contrib

http://pyvideo.org/video/1660/documenting-your-project-in-sphinx


Indices and tables
==================

* :ref:`genindex`
* :ref:`search`