Documentation du code avec Sphinx

Les informations utiles aux développeurs de Pyromaths.

Modérateur : Développeurs

Avatar de l’utilisateur
Jérôme
Administrateur - Site Admin
Messages : 1083
Inscription : 26 août 2006, 13:10
Localisation : Nantes
Contact :

Documentation du code avec Sphinx

Message par Jérôme » 17 mai 2013, 22:58

Bonsoir,
j'ai donc commencer à regarder de plus prêt le fonctionnement de Sphinx.
Vous trouverez un aperçu à l'adresse suivante : http://docs.pyromaths.org/
L'idée serait de documenter les classes et outils de Pyromaths. je ne suis pas certain que la documentation des exercices soit nécessaire. C'est un gros travail de remise au propre du code, mais je suis convaincu que ce serait bénéfique pour le développement de Pyromaths. De plus, cela permet de s'apercevoir des erreurs et incongruités dans le code. Je sais à présent que la classe Fractions est à réécrire : c'est tout moche, c'était mes débuts en code objet et ça ne ressemble à rien.
J'ai totalement documenté la classe PolynomesCollege, cela vous permettra vous faire une idée du résultat.
À bientôt.
Pyromaths génère des fiches d'exercices et leur corrigé en toute simplicité.
Un programme multi-plateformes libre et gratuit sous licence GPL

Avatar de l’utilisateur
Arnaud
Critique officiel de pyromaths
Messages : 609
Inscription : 26 août 2006, 21:49
Localisation : Allemagne
Contact :

Re: Documentation du code avec Sphinx

Message par Arnaud » 18 mai 2013, 09:49

Bon démarrage. On sent la motivation d'après guerre qui donne des ailes pour se lancer dans tous les projets :)

Cela me paraît également nécessaire, car voulant utiliser des outils existants, je me suis rendu compte que :

1) certaines fonctions sont en double, avec quasiment la même utilité,
2) les descriptions de certaines fonctions sont trop minimales et ne permettent pas du tout de comprendre ce qu'il se passe si on ne rentre pas dans le code,
3) il manque la description des types de variables d'entrée, de sortie.

C'est aussi le cas dans mes propres programmes, dont je n'ai pas réussi à comprendre la description après coup :oops:

En plus de cela, puisque c'est lié, il me semble nécessaire de restructurer l'ensemble, en classant d'un côté les outils algébriques, les outils arithmétiques, les outils géométriques, les outils pour la syntaxe latex, plutôt que de les chercher à plusieurs endroits dans les exercices.

Je suis partant pour attaquer, mais après mes vacances ( même probablement seulement en été ), je pars ce soir pour 2 semaines dans le sud, sans vraiment de net.

Avatar de l’utilisateur
Jérôme
Administrateur - Site Admin
Messages : 1083
Inscription : 26 août 2006, 13:10
Localisation : Nantes
Contact :

Re: Documentation du code avec Sphinx

Message par Jérôme » 18 mai 2013, 10:43

En effet, ça fait quelques temps que j'ai envie de m'y remettre, d'autant plus qu'il y a eu beaucoup d'activité par ici. C'est enfin possible.
Je crois aussi avoir essayé de documenter mon code, mais je me suis aperçu en utilisant Sphinx que tout est trop sommaire. Le typage des objets en entrée et en sortie me semble indispensable. Les exemples de code et de sortie que permet Sphinx sont vraiment très parlants. C'est un chouette outil.
Par contre, je ne comprends pas pourquoi dans la version en ligne il manque le bandeau... J'avais inséré le bandeau Pyromaths d'Arnaud et il n'apparaît pas (bandeau.png dans le code source de la page html). Étonnant.
Tout à fait d'accord sur la nécessité de mieux structurer l'ensemble.
Bonnes vacances Arnaud, et bon week-end aux autres.
Pyromaths génère des fiches d'exercices et leur corrigé en toute simplicité.
Un programme multi-plateformes libre et gratuit sous licence GPL

Avatar de l’utilisateur
Yves
Messages : 456
Inscription : 21 janv. 2009, 20:40
Contact :

Re: Documentation du code avec Sphinx

Message par Yves » 18 mai 2013, 11:26

Pour afficher le bandeau Pyromaths , il faut rajouter media="print" pour la feuille de style pour l''impression ;) :
<link rel="stylesheet" href="_static/print.css" type="text/css" media="print"/>
Par ailleurs, tu peux franciser ta documentation Sphinx en rajoutant dans conf.py
language = 'fr'
à la place de
#language = None

Avatar de l’utilisateur
Jérôme
Administrateur - Site Admin
Messages : 1083
Inscription : 26 août 2006, 13:10
Localisation : Nantes
Contact :

Re: Documentation du code avec Sphinx

Message par Jérôme » 18 mai 2013, 20:20

Merci Yves,
je n'avais pas encore vu l'option language. Ce sera plus joli.
Je ne comprends pas pourquoi quand je lis les fichiers html chez moi, j'ai bien le bandeau, alors que quand je les lis à partir du serveur, il n'apparaît pas. Et ajouter media="print" oblige à modifier le template. C'est ennuyeux.
Pyromaths génère des fiches d'exercices et leur corrigé en toute simplicité.
Un programme multi-plateformes libre et gratuit sous licence GPL

Avatar de l’utilisateur
Yves
Messages : 456
Inscription : 21 janv. 2009, 20:40
Contact :

Re: Documentation du code avec Sphinx

Message par Yves » 18 mai 2013, 23:16

La feuille de style destinée à l'impression n'inclut volontairement pas le bandeau Pyromaths avec le code #toc { display: none; }. Si le média print n'est pas précisé, c'est le média all qui est la valeur par défaut, selon les recommandations du W3C. Le fait que le média print ne soit pas explicitement stipulé dans le template est donc un bug. Modifier le template, c'est corriger le bug et du coup ce n'est pas si ennuyeux que ça ;) L'idéal serait un fix upstream.

fabienm
Messages : 28
Inscription : 06 nov. 2012, 00:20

Re: Documentation du code avec Sphinx

Message par fabienm » 19 mai 2013, 12:29

Félicitation jérome au fait, je viens de voir sur publinet :)

Avatar de l’utilisateur
djinn
Messages : 183
Inscription : 03 mars 2013, 10:38

Re: Documentation du code avec Sphinx

Message par djinn » 19 mai 2013, 12:47

Ah, ça fait plaisir de voir toute cette activité! :)

Je soutiens activement la démarche documentation et réorganisation du code, notamment pour le rendre plus accessible.
J'ai deux grandes idées à soumettre pour ce qui est de l'architecture du code:
  1. Exercices: découverte automatique (plus de référencement manuel), possibilité d'ajouter des exercices séparément du reste du programme.
  2. Interface utilisateur: séparation entre le cœur de pyromaths (générateur d'exercices) et l'interface utilisateur (Qt), possibilité d'utiliser le core comme librairie (je pense à jbreizh), de l'appeler en ligne de commande (comme je le fais) ou de coder de nouvelles UI (wxPython, ncurses…).
Ce n'est pas le bon fil pour en discuter en détail, mais l'idée serait de regrouper le code en trois ensembles/packages:

Code : Tout sélectionner

 +--------------+
 | pyromaths.ui |     Interfaces Utilisateur
 +--------------+
        |
    interface
        |
        V
+----------------+
| pyromaths.core |    Générateur d'exercices TeX/pdf
+----------------+
        |
    interface
        |
        V
 +--------------+
 | pyromaths.ex |     Exercices
 +--------------+

Avatar de l’utilisateur
djinn
Messages : 183
Inscription : 03 mars 2013, 10:38

Re: Documentation du code avec Sphinx

Message par djinn » 19 mai 2013, 12:53

fabienm a écrit :Félicitation jérome au fait, je viens de voir sur publinet :)
Tu es reçu?

Avatar de l’utilisateur
Jérôme
Administrateur - Site Admin
Messages : 1083
Inscription : 26 août 2006, 13:10
Localisation : Nantes
Contact :

Re: Documentation du code avec Sphinx

Message par Jérôme » 19 mai 2013, 19:00

djinn a écrit :
fabienm a écrit :Félicitation jérome au fait, je viens de voir sur publinet :)
Tu es reçu?
Yes ! :D
Merci beaucoup, je suis très heureux. Et je peux de nouveau venir jouer à Pyromaths avec vous ;)
Pyromaths génère des fiches d'exercices et leur corrigé en toute simplicité.
Un programme multi-plateformes libre et gratuit sous licence GPL

Avatar de l’utilisateur
Jérôme
Administrateur - Site Admin
Messages : 1083
Inscription : 26 août 2006, 13:10
Localisation : Nantes
Contact :

Re: Documentation du code avec Sphinx

Message par Jérôme » 19 mai 2013, 19:13

Yves a écrit :Pour afficher le bandeau Pyromaths , il faut rajouter media="print" pour la feuille de style pour l''impression ;) :
<link rel="stylesheet" href="_static/print.css" type="text/css" media="print"/>
Par ailleurs, tu peux franciser ta documentation Sphinx en rajoutant dans conf.py
language = 'fr'
à la place de
#language = None
Merci pour les infos Yves. C'est à présent corrigé.
Pyromaths génère des fiches d'exercices et leur corrigé en toute simplicité.
Un programme multi-plateformes libre et gratuit sous licence GPL

Avatar de l’utilisateur
djinn
Messages : 183
Inscription : 03 mars 2013, 10:38

Re: Documentation du code avec Sphinx

Message par djinn » 20 mai 2013, 10:23

Jérôme a écrit :Yes ! :D
Félicitations. :)

Avatar de l’utilisateur
Jérôme
Administrateur - Site Admin
Messages : 1083
Inscription : 26 août 2006, 13:10
Localisation : Nantes
Contact :

Re: Documentation du code avec Sphinx

Message par Jérôme » 20 mai 2013, 10:29

Merci :)
Pyromaths génère des fiches d'exercices et leur corrigé en toute simplicité.
Un programme multi-plateformes libre et gratuit sous licence GPL

Avatar de l’utilisateur
Jérôme
Administrateur - Site Admin
Messages : 1083
Inscription : 26 août 2006, 13:10
Localisation : Nantes
Contact :

Re: Documentation du code avec Sphinx

Message par Jérôme » 20 mai 2013, 10:45

J'ai avancé un peu sur la documentation. C'est un peu déprimant, car je vois tellement de choses à corriger que je ne sais plus par où commencer...
Le module Arithmétique est plutôt propre (merci Arnaud) mais deux fonctions n'ont rien à y faire.
La classe Fraction est à réécrire. Le module Affichage est bancal. Je voudrais écrire une fonction qui prenne un calcul en entrée et s'occupe de le transformer en LaTeX. Je m'y mets dès que j'ai fini la doc.
Pyromaths génère des fiches d'exercices et leur corrigé en toute simplicité.
Un programme multi-plateformes libre et gratuit sous licence GPL

Avatar de l’utilisateur
djinn
Messages : 183
Inscription : 03 mars 2013, 10:38

Re: Documentation du code avec Sphinx

Message par djinn » 20 mai 2013, 11:13

C'est le grand ménage de printemps… Pyromaths 2.0 ? ;)

Répondre