Documentation du code avec Sphinx

[fabienm]

pour réorganiser le code des exos je pense qu'il faudrait se mettre d'accord sur certaines conventions (tous les noms d'exo commencent par exo_nomdelexo par exemple).

[djinn]

Oui.
Il faudrait également abandonner le nommage des packages d'exos en fonction du "niveau", comme on en a déjà discuté précédemment. Si on ne veut pas les mettre tous dans le même panier, pour des raisons de clarté, on peut peut-être utiliser des packages "domaine" à la place?
Il faudrait enfin que tous ces packages d'exos ne soient pas mélangés aux autres packages de code/GUI, que l'on puisse les identifier du premier coup d'œil (et éventuellement les découvrir dynamiquement). Par exemple en les rassemblant dans un "meta-package" (i.e. un sous-dossier dédié).

[fabienm]

Par domaine c'est délicat... Certains exos devront être disponible dans plusieurs domaines, comment on gère ça avec ton idée ?

[jbreizh]

hello,
perso je l'ai fait et du coup j'ai coupé la poire en 2 : niveau_domaine_nom.py car quand on veut faire un module fraction pour les 5emes, 4eme et 3eme bah je pense que c'est plus clair de faire cinquieme_NombreCalcul_fraction.py quatrieme_NombreCalcul_fraction.py .... plutot que de faire nombreCalcul_fraction1.py nombreCalcul_fraction2.py .... Mais bon depuis que je me suis acheté un ecran hd, je suis fan des noms à rallonge à la limite les commentaire ne servent à rien
Par contre depuis que j'ai vu la version de moodle proposé par notre ami espagnol, il me parait clair que les exercices doivent être former un package tel que:

|--------------------------------------------------------
| exercice1.py exercice2.py ......... system.py |
| -------------------------- ------------------------- |
| | outil | | classes | |
| -------------------------- ------------------------- |
|-------------------------------------------------------|
En clair le package d'exercice doit etre independant et présenter tous ce qui permet la génération des dits exercices. Actuellement les exercices pyromaths peuvent former un package (comme dans ma version) ceux d'actimaths un autre et si le projet moodle se poursuit on en aura un autre.
Au dessus de ces packages d'exercices, l'interface (ou les interfaces) qui permet la generation de "parametre". Pour moi, "parametre" est l'api permettant de communiquer avec le coeur de pyromaths. Il faut donc fixer cette api que chacun (developpeur du coeur system, des exercices et de l'interface) puissent bosser chacun sur son truc sans devoir se soucier de ce qui se passe avant ou après. Après on a une interface en QT, en HTML (d'ailleurs je serais super interessé de voir les sources ) et aussi un sorte d'interface dans le script de génération des vignettes..... Après l'avenir est je pense à l'interface web qui est multiplate forme par essence (genre une demarche comme celle ci me parait interessante: http://code-weblog.com/developper-une-webapp-en-python/ )
Aller bon lundi

[djinn]

Par domaine c'est délicat... Certains exos devront être disponible dans plusieurs domaines, comment on gère ça avec ton idée ?

En fait, tel que je le vois, il faut un critère -- même arbitraire -- pour regrouper les fichiers d'exercices, et ainsi éviter le dossier/package fourre-tout. JB ne fait pas autre chose, finalement, en regroupant ses exercices en dossiers pyromaths, actimaths, etc.
Même en prenant le domaine comme critère, il faut le distinguer du domaine de la couche de présentation: pour celle-ci, je verrais plutôt un mécanisme de tag, pour pouvoir attribuer plusieurs tags (relatifs ou non au domaine) à un même exercice. Autrement dit, l'appartenance d'un exercice à un domaine serait éventuellement représentée deux fois: le package auquel il appartient, et un tag dans le fichier exercice considéré.
Pour que les choses soient claires, peu m'importe le critère qui est choisi, je pense juste important d'éviter la situation où tout les fichiers exercices se retrouvent dans le même dossier.

D'autant plus que j'aimerais déplacer les vignettes à côté du code exercice qu'elles illustrent. Ce qui permet:

1. D'ajouter un groupe d'exercices (et leur vignettes) en copiant un sous-dossier ou en important un nouveau package.
2. De reconstruire automatiquement une vignette lorsque le code exercice correspondant a changé (make).
3. De respecter l'esprit de distutils: de part leur relation intime au code qu'elles illustrent, ces vignettes sont des package_data qui devraient figurer quelque part dans src/, et pas des data_files situés dans data/ comme c'est le cas aujourd'hui.

Pour qu'on s'y retrouve, et pour que (b) fonctionne en l’occurrence, il faut que le fichier python et le fichier vignette aient à peu près le même nom ou respectent un format simple.

[djinn]

Je crois qu'on sera tous d'accord: le plus simple pour organiser les exercices en groupes (de manière à clarifier le code et permettre leur import/export par paquets) c'est d'en faire des packages, comme c'est ce cas actuellement.
Ce qu'on peut améliorer, je pense, c'est la façon dont un tel package d'exercices se plug dans pyromaths: une unique déclaration devrait suffire; Voire, dans l'idéal, les packages d'exercices disponibles sont découverts dynamiquement, au runtime.
Si les exercices doivent être référencés individuellement et statiquement quelque part, cette liste devrait être maintenue au sein du package (pas dans Values.py), et intégrée par pyromaths seulement au runtime quand il importe ce package. Autrement dit, elle devrait probablement figurer dans le fichier __init__.py de ce package.
Comme l'a souligné JB, on peut aussi améliorer l'intégration de ces packages en y ajoutant tout ce qui leur est nécessaire, à commencer probablement par un sous-dossier img/ contenant les vignettes des exercices considérés; peut-être un sous-dossier doc/ si nécessaire. Est-ce que tu penses à ajouter un autre type de fichier (comme des modèles TeX) JB?

Puis vient l'interface "exercice" en elle-même.
Aujourd'hui, un exercice est une simple fonction renvoyant un tuple de string (enoncé,correction). Ça a l'avantage d'être simple, on peut mettre ces fonctions un peu où on veut du moment qu'on les référence quelque part (dans Values.py et bientôt j'espère dans __init__.py).
Par contre, c'est pas très flexible: notre ami espagnol rajoute me semble-t-il un élément moodle au tuple de retour. J'avais un problème similaire en voulant ajouter à l'énoncé et à la correction complète, un "énoncé corrigé". Si on voulait pouvoir tagguer un exercice, comment faire avec ce modèle?
Je pense qu'on va devoir passer à un modèle objet, où chaque type d'exercice est une classe, définie dans un fichier python, adossé à un fichier vignette. Cette classe hérite d'une classe abstraite, modèle ou squelette d'exercice qui définit précisément notre interface "exercice". On a alors tout le loisir d'ajouter d'éventuels tags de catégorie, ou une méthode de test, etc.

[jbreizh]

hello,
tes compétences sont largement au dessus des miennes et je t'avoue que je suis à la peine sur la question de la programmation objet. Je comprends les concepts, mais je manque de pratique (la dernière fois c'était du java pendant mes études...). Par contre je connais parfaitement le fonctionnement de pyromaths actuellement et je perçois que ta proposition est la bonne. J'ai moi même simplifié le fonctionnement actuel en supprimant le fichier niveau.py (sixieme.py, cinquieme.py) et LESFICHES dans values.py. Cette séparation etait très actificielle et uniquement basée sur l'index dans une liste. En plus il y avait duplication de code dans chaque niveau.py. J'ai donc centralisé ce code dupliqué (c'est du code de génération des exercices+l'appel des fonction) dans system.py et j'ai regroupé toutes les informations sur les exercices dans des fichiers xml (nom, domaine, niveau, description, commande). L'import des différents exercices se fait dans __init__.py du package exercice.
Ma solution n'est pas encore la bonne du fait que la structure de mes fichiers xml est celle de mon interface, il n'ya pas donc réelle séparation entre interface et system.

Effectivement on peut integrer déjà intégrer les vignettes et les modèles latex ou xml dans le cas de moodle. Je pense qu'un autre objectif est de bannir la mise en forme dans les exercices qui devrait par exemple retourner toutes les questions séparement ((enonce,question1,question2....),(enonce,corrigé1,corrigé2...)). C'est au post traitement de faire la mise en page selon des templates (latex, xml, html....). C'est l'ojectif que je me suis donné (même si je suis rester à(exo,cor,question) dans mon system.py : la construction du fichier tex est uniquement faite par insertion dans le template, il n'y a aucun code latex hard-codé dans mon system.py. Si on pousse le concept jusqu'au bout, on peut vraiment avoir un truc très flexible qui pourra nous sortir des documents aux formes très différentes et dans des langages différent (tex, xml avec moodle, html avec mathjax....)

[djinn]

Je suis entièrement d'accord avec toi. Il est intéressant de voir qu'on arrive aux mêmes conclusions par des chemins différents. Ça m'incite à penser que c'est la bonne direction.
On devrait créer un fil pour discuter de cette API exercice…

Pour revenir au sujet de ce fil, j'ai regardé le résultat HTML de la doc. Bravo, Jérôme, ça rend plus que bien.
Une remarque: est-ce que ça t'ennuierait qu'on renomme Doc/ en minuscules (doc/), comme les autres dossiers?

Si j'ai bien compris, le package pyromaths/classes rassemble des outils qui se présentent sous forme de classe plutôt que de fonction? Si c'est le cas, est-ce que ça mérite vraiment un package à part? Fonctionnellement parlant, il me semble que ce sont des pyromaths/outils, non?

[fabienm]

Faudrait surtout que ça devienne pas une usine à gaz N'oublions pas que le mieux est l'ennemi du bien !

J'aimerais bien m'impliquer la dedans mais je sais pas comment vous faites pour trouver du temps... Vous êtes tous célibataires sans enfants ou quoi ?

Bon je m'arrête ça sonne je vais faire des systemes avec mes 3emes...

[djinn]

Faudrait surtout que ça devienne pas une usine à gaz N'oublions pas que le mieux est l'ennemi du bien !

En effet, il est important de garder la simplicité en tête.
Pour autant, ce dont on parle avec JB consiste précisément à rationaliser une usine à gaz existante, à la réorganiser en trois unités de productions intégrées et bien délimitées: l'interface utilisateur, le générateur, les exercices. En règle générale, il ne s'agit pas de rajouter des tuyaux mais plutôt d'en enlever, ou du moins de les raccourcir.
Relis hello world par exemple: les deux-tiers n'ont rien à voir avec la fabrication d'un exercice mais détaillent comment référencer cet exercice dans niveau/niveau.py (doublon malheureux de niveau/__init__.py) et Values.py. Avec "notre" version, cette page serait probablement plus courte ou, au moins, plus centrée sur l'exercice lui-même, son format, ses options…

Dans certain cas cette approche peut même s'avérer plus verbeuse pour le meilleur: si chaque exercice se retrouvait dans son propre fichier python, par exemple, il y aurait plus de redondances qu'en rassemblant plusieurs exercices dans le même fichier. Pour autant, les choses en seraient probablement plus claires et donc plus faciles d'accès pour un nouveau-venu -- qu'il s'agisse de lui expliquer comment créer un nouvel exercice (tu crées un fichier avec ce format) ou qu'il cherche à retrouver le code générant tel exercice qu'il souhaite modifier.
D'autre part, un exercice est quelque chose d'important: il doit avoir sa propre vignette, ses propres traductions, sa méthode de test; pourquoi pas son fichier source individuel?

[Jérôme]

Ça bosse dur par ici !
À l'origine, j'aurais aimé que Pyromaths crée du TeX ou du odt. Et puis je me suis dit que ça serait trop contraignant. Votre idée de séparer exercice et codage m’intéresse donc. Mais comment pourrions-nous faire en pratique ? Je pense à une liste par exemple. Il faut bien la coder d'une manière ou d'une autre.

[Yves]

si chaque exercice se retrouvait dans son propre fichier python, par exemple, il y aurait plus de redondances qu'en rassemblant plusieurs exercices dans le même fichier. Pour autant, les choses en seraient probablement plus claires et donc plus faciles d'accès pour un nouveau-venu -- qu'il s'agisse de lui expliquer comment créer un nouvel exercice (tu crées un fichier avec ce format) ou qu'il cherche à retrouver le code générant tel exercice qu'il souhaite modifier.
D'autre part, un exercice est quelque chose d'important: il doit avoir sa propre vignette, ses propres traductions, sa méthode de test; pourquoi pas son fichier source individuel?

Je suis entièrement favorable à ce concept.

[jbreizh]

J'ai commancé à réorganiser mon code pour inclure les vignettes, modèles et info sur les exercices (pour moi des fichiers xml) dans le package exercice.
Par contre il y a 2 questions que je me pose du coup:
- l'utilité du dossier data qui ne contient plus que les icones de pyromaths. Est ce que cela vaut le coup de s'embêter (voir values.py) avec un tel dossier?
- Comment on fait le packaging ? Pour le moment c'est "data_files" qui fait le boulot, mais la il faut faire comment ? Et ça veut dire que les vignettes et compagnie se retrouvent dans le .exe sous windows, grave ou pas ?

Sinon je suis aussi favorable au un exercice = un fichier. D'autant que si l'utile est à sa place dans outils, ça devrait le faire niveau replication. Le plus "sale" dans le lot sont les exercices de troisieme et de quatrième ou il y a des référence croisées entre les exos (au lieu d'être dans outils)

[djinn]

À l'origine, j'aurais aimé que Pyromaths crée du TeX ou du odt. (...) Mais comment pourrions-nous faire en pratique ? Je pense à une liste par exemple. Il faut bien la coder d'une manière ou d'une autre.

J'avoue que pour l'instant, personnellement, j'en suis resté à TeX. Comme disait Clint: «Le monde se divise en deux catégories, ceux qui utilisent un bête traitement de texte et ceux qui utilisent Tex». J'ai choisi mon camp.
Je ne suis pas certain que ce que tu suggères soit ce dont parlait JB. Ceci dit, à mon sens, le problème si on voulait être compatible odt, c'est qu'on serait obligé de coder une couche intermédiaire qui traduise nos instructions en TeX ou odt. J'en frémis rien que d'y penser: énormément de travail, restriction au pgcd des fonctionnalités, résultat imparfait quasi-garanti dans les deux formats…
Personnellement, je ne suis pas prêt à abandonner quoi que ce soit de la qualité TeX. Du coup, même si j'aime bien l'idée en théorie, je doute qu'elle soit aussi bonne en pratique. Ou alors, il faudrait trouver une couche de conversion toute faite TeX->odt?

J'ai commancé à réorganiser mon code pour inclure les vignettes, modèles et info sur les exercices (pour moi des fichiers xml) dans le package exercice.
Par contre il y a 2 questions que je me pose du coup:
- l'utilité du dossier data qui ne contient plus que les icones de pyromaths. Est ce que cela vaut le coup de s'embêter (voir values.py) avec un tel dossier?
- Comment on fait le packaging ? Pour le moment c'est "data_files" qui fait le boulot, mais la il faut faire comment ? Et ça veut dire que les vignettes et compagnie se retrouvent dans le .exe sous windows, grave ou pas ?

data/ devrait contenir tout ce qui est défini comme data_files, autrement dit tout ce qui est susceptible d'être installé en dehors de l'arborescence pyromaths (au moins sur certaines plateformes): c'est le cas des icônes, des man-pages Unix (/usr/share/man/man1/pyromaths.1), du lanceur (usr/share/applications/pyromaths.desktop), du fichier de config par défaut (pyromaths.xml) s'il existait, etc. Ces éléments sont installés ailleurs que dans l'arborescence pyromaths car ils sont utilisés par d'autres parties du système, ou pour se conformer à des emplacements standards. En pratique, ça ne concerne pour l'instant qu'Unix car nous distribuons pyromaths comme application standalone sur les autres plateformes.
Tout ce qui n'est utilisé que par pyromaths et demeure dans son arborescence devrait être situé quelque part dans src/ et défini dans setup.py comme package_data. C'est le cas des vignettes d'exercices et des modèles TeX sur-mesure. Ceci dit, entre setuptools, py2exe et py2app qui ont tous leur interprétation légèrement déviante de ces arguments distutils (data_files et package_data), j'imagine qu'il va falloir légèrement adapter le code de packaging…

[djinn]

J'ai créé un fil de discussion séparé pour la question de l'API-Exercice. Qu'on arrête de polluer ce fil qui traite de documentation…
J'ai également créé une nouvelle branche git (exapi) pour accueillir les patchs correspondants.

Faudrait surtout que ça devienne pas une usine à gaz

Pour l'instant j'ai enlevé plus de code que je n'en ai ajouté, j'ai rationalisé un ou deux processus, et j'ai mis en place la découverte automatique des exercices au runtime.
Du coup, la seule chose qui change du point de vue d'un développeur d'exercice, c'est qu'il n'y a plus besoin de référencer sa fonction dans niveau.py:main(), ni son titre dans Values.py:LESFICHES. N'importe quelle fonction située dans un package d'exercices et ayant une propriété description est automatiquement découverte et affichée dans l'interface graphique:

def exercice():
    ...
    return (enonce, correction)

exercice.description = u'Titre exercice'

Cela devrait faciliter la transition vers une nouvelle API-Exercice, une fois qu'elle aura été définie: en ajoutant le nouveau format à la découverte automatique, on pourra traduire les exercices d'un format à l'autre petit à petit.

- Comment on fait le packaging ? Pour le moment c'est "data_files" qui fait le boulot, mais la il faut faire comment ?

J'ai fait ce genre de modifs packaging dans exapi, si tu veux un exemple (les vignettes étant déplacées dans un sous-dossier img/ du package d'exercice correspondant). Tout a l'air de fonctionner correctement sous Linux, mais il faut encore tester le packaging windoz et Mac…