Documentation du code avec Sphinx

Les informations utiles aux développeurs de Pyromaths.

Modérateur: Développeurs

Documentation du code avec Sphinx

Messagede Jérôme » Ven 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
Jérôme
Administrateur - Site Admin
 
Messages: 1062
Inscription: Sam 26 Aoû 2006, 13:10
Localisation: Nantes

Re: Documentation du code avec Sphinx

Messagede Arnaud » Sam 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
Arnaud
Critique officiel de pyromaths
 
Messages: 603
Inscription: Sam 26 Aoû 2006, 21:49
Localisation: Allemagne

Re: Documentation du code avec Sphinx

Messagede Jérôme » Sam 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
Jérôme
Administrateur - Site Admin
 
Messages: 1062
Inscription: Sam 26 Aoû 2006, 13:10
Localisation: Nantes

Re: Documentation du code avec Sphinx

Messagede Yves » Sam 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
Yves
 
Messages: 453
Inscription: Mer 21 Jan 2009, 21:40

Re: Documentation du code avec Sphinx

Messagede Jérôme » Sam 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
Jérôme
Administrateur - Site Admin
 
Messages: 1062
Inscription: Sam 26 Aoû 2006, 13:10
Localisation: Nantes

Re: Documentation du code avec Sphinx

Messagede Yves » Sam 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.
Avatar de l’utilisateur
Yves
 
Messages: 453
Inscription: Mer 21 Jan 2009, 21:40

Re: Documentation du code avec Sphinx

Messagede fabienm » Dim 19 Mai 2013, 12:29

Félicitation jérome au fait, je viens de voir sur publinet :)
fabienm
 
Messages: 28
Inscription: Mar 06 Nov 2012, 01:20

Re: Documentation du code avec Sphinx

Messagede djinn » Dim 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: Dim 03 Mar 2013, 11:38

Re: Documentation du code avec Sphinx

Messagede djinn » Dim 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
djinn
 
Messages: 183
Inscription: Dim 03 Mar 2013, 11:38

Re: Documentation du code avec Sphinx

Messagede Jérôme » Dim 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: 1062
Inscription: Sam 26 Aoû 2006, 13:10
Localisation: Nantes

Re: Documentation du code avec Sphinx

Messagede Jérôme » Dim 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
Jérôme
Administrateur - Site Admin
 
Messages: 1062
Inscription: Sam 26 Aoû 2006, 13:10
Localisation: Nantes

Re: Documentation du code avec Sphinx

Messagede djinn » Lun 20 Mai 2013, 10:23

Jérôme a écrit:Yes ! :D

Félicitations. :)
Avatar de l’utilisateur
djinn
 
Messages: 183
Inscription: Dim 03 Mar 2013, 11:38

Re: Documentation du code avec Sphinx

Messagede Jérôme » Lun 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: 1062
Inscription: Sam 26 Aoû 2006, 13:10
Localisation: Nantes

Re: Documentation du code avec Sphinx

Messagede Jérôme » Lun 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
Jérôme
Administrateur - Site Admin
 
Messages: 1062
Inscription: Sam 26 Aoû 2006, 13:10
Localisation: Nantes

Re: Documentation du code avec Sphinx

Messagede djinn » Lun 20 Mai 2013, 11:13

C'est le grand ménage de printemps… Pyromaths 2.0 ? ;)
Avatar de l’utilisateur
djinn
 
Messages: 183
Inscription: Dim 03 Mar 2013, 11:38

Suivante

Retourner vers Documentation

Qui est en ligne

Utilisateurs parcourant ce forum: Aucun utilisateur enregistré et 3 invités

cron