La documentation de GNSI

Ce programme suppose que vous disposiez d'une installation latex qui fonctionne. Si vous voulez faire des tests, je vous invite à d'abord modifier le fichier brouillon.tex dans le dossier modeles et vérifier que cela fonctionne lors de la mise au point du fichier latex d'un exercice.

Une fois que vous êtes satisfait, vous pouvez adapter le fichier document_debut.tex (jusqu'à \begin{document}) en veillant bien à définir l'entềte ainsi :

\title{\VAR{titre}}
\author{\VAR{auteur}}
\date{\VAR{date}}

car il s'agit d'un template jinja2.

La version pdf de ce document est ici : documentation_gnsi.pdf

Les sources peuvent être récupérées à l'adresse : https://framagit.org/Patrice/gnsi

En utilisant git,

git clone https://framagit.org/Patrice/gnsi.git

Personnellement, pour simplifier la configuration du module en vue d'un futur dépôt sur https://pypi.org/, j'ai utilisé le package flit :

pip install flit

Se déplacer dans le dossier gnsi :

cd gnsi

Puis lancer l'installation avec flit :

flit install

Pour ceux qui veulent utiliser un environnement virtuel, il faut activer celui-ci puis lancer la commande :

flit install --env

Si l'installation s'est bien déroulée, en lançant la ligne suivante :

gnsi -h

vous devriez voir :

usage: gnsi [-h]
            {brouillon,classe,configuration,corriger,devoir,new,ramasser} ...

Fonction principale

optional arguments:
  -h, --help            show this help message and exit

Available subcommands:
  {brouillon,classe,configuration,corriger,devoir,new,ramasser}
    brouillon           Permet de manipuler le brouillon de l'exercice avant
                        de l'ajouter à la base.
    classe              Permet de gérer les fichiers avec les données élèves.
    configuration       Affiche le fichier de configuration.
    corriger            Corrige les travaux élèves qui ont été ramassés et
                        placés dans le dossier du devoir.
    devoir              Crée un dossier devoir,sa feuille de correction AMC,
    new                 Créer les dossiers et le fichier de configuration
                        adéquate.
    ramasser            Place l'archive Moodle dans le dossier du devoir.

gnsi new

Il vous sera demandé un nom de dossier à créer dans votre répertoire personnel. Par défaut, GNSIcontenus.

Il vous est également proposé de changer le nom par défaut d'un exercice. Vous pouvez trouver sur ce dépôt le projet GNSIexercices qui contient les exercices prêts à l'emploi que j'ai déjà saisi. Si chacun développe sa branche avec ses propres noms d'exercice, cela éviterait les conflits au moment de la fusion de branches. Je propose la convention "exercice"+ initiales, sachant que la numérotation des exercices est automatisée.

Si on n'a qu'une seule classe, autant en faire la classe par défaut :

gnsi classe --ajouter --defaut nom_de_la_classe addresse_absolue_fichier_donnees_eleves.csv

• nom_de_la_classe est un alias qui sert à désigner la classe. Il est surtout utile quand on en a plusieurs.
• addresse_absolue_fichier_donnees_eleves.csv est un fichier csv (le séparateur doit être une virgule). La première ligne doit contenir le nom des champs qui sont obligatoirement :
  • id : un nombre, identifiant unique ;
  • eleve : le nom de l'élève tel qu'il apparaît dans Moodle. Quand vous récupérer des travaux, Moodle place les travaux de chaque élève dans un dossier qui commence par son nom. En général, c'est prenom + " " + nom.
  • prenom : le prénom de l'élève ;
  • nom : son nom
  • idmoodle : l'identifiant Moodle de l'élève.
  • email : l'adresse mail de l'élève.

Pour les 4 derniers champs, vous pouvez exporter le carnet de notes de Moodle, pour avoir ces données.

gnsi classe --ajouter nom_de_la_classe addresse_absolue_fichier_donnees_eleves.csv

Pour vérifier la configuration :

gnsi configuration

brouillons  :  /**********/GNSIcontenus/brouillons
brouillons/docs  :  /**********/GNSIcontenus/brouillons/docs
brouillons/latex  :  /**********/GNSIcontenus/brouillons/latex
exercices  :  /**********/GNSIcontenus/exercices
devoirs  :  /**********/GNSIcontenus/devoirs
modeles  :  /**********/GNSIcontenus/modeles
latex  :  xelatex
reader  :  evince
test  :  nosetests3
nom  :  exercice
term  :  /**********/GNSIcontenus/modeles/eleves_nsi_2122.csv
defaut  :  /**********/GNSIcontenus/modeles/eleves_nsi_2122.csv

Vous pouvez modifier ce fichier manuellement : ~/.config/gnsi/config_gnsi.cfg.

Vous remarquerez que le logiciel par défaut pour la compilation latex est xelatex, et celui pour la lecture de pdf evince.

En revanche, le logiciel pour effectuer les tests n'est pas modifiable mais doit être installé sur votre système. Si ce n'est pas le cas :

pip install nosetests

gnsi fonctionne avec une sous commande et des arguments. Pour connaître les arguments de la sous-commande brouillon, il suffit de lancer :

gnsi brouillon -h

usage: gnsi brouillon [-h] [--clean] [--no-clean] [--importer] [--no-importer]
                      [--tester] [--no-tester] [--force] [--no-force] [--pdf]
                      [--no-pdf] [--preparer] [--no-preparer] [--exporter]
                      [--no-exporter] [--corriger] [--no-corriger]
                      [args [args ...]]

Permet de manipuler le brouillon de l'exercice avant de l'ajouter à la base.

positional arguments:
  args

optional arguments:
  -h, --help     show this help message and exit
  --clean        Vide le dossier brouillons (default: False)
  --no-clean
  --importer     Importer les fichier (adresse absolue) dans le dossier
                 brouillons. (default: False)
  --no-importer
  --tester       Génère tous les formats à partir du fichier markdown et lance
                 les tests. (default: False)
  --no-tester
  --force        Impose la regénération du fichier latex (default: False)
  --no-force
  --pdf          Lance la compilation du fichier latex et visualise le pdf.
                 (default: False)
  --no-pdf
  --preparer     Nomme l'exercice et génère le pdf avec ce nom. (default:
                 False)
  --no-preparer
  --exporter     Ajoute l'exercice à la base de données et l'enlève des
                 brouillons. (default: False)
  --no-exporter
  --corriger     Réimporte un exercice existant pour le corriger. (default:
                 False)
  --no-corriger

gnsi brouillon --clean

Cette commande efface toute trace d'un exercice précédent. On a alors l'arborescence suivante.

Les fichiers setup.cfg et brouillon.tex sont recopiés à partir du dossier modeles par conséquent si vous voulez les modifier de manière pérenne, il faut les modifier dans ce dernier.

• setup.cfg est un fichier de configuration pour nosetests. Les paramètres permettent de chercher les doctests dans le dossier docs. Les résultats seront affichés dans la console.
• brouillon.tex est un document maître latex qui charge le fichier exercice.tex qui se trouve dans le dossier latex.

Il s'agit de créer 2 fichiers dont les noms sont obligatoirement les suivants :

• exercice.md : l'énoncé au format markdown avec quelques métadonnées (voir si après). À partir de ce fichier seront générés :

  • exercice_version_eleve.md : à la racine du dossier brouillons, un énoncé pour l'élève qui peut éventuellement servir de fichier doctest.
  • exercice.tex : dans le dossier latex.

  Ces deux fichiers ne sont générés qu'une seule fois mais il sera possible de relancer cette génération. Il sera donc possible de les personnaliser avant d'exporter l'exercice dans la base.

  • des fichiers de tests au format markdown. Ceux-ci seront placés dans le dossier docs.
  • bareme.csv : à la racine du dossier brouillons, un fichier qui contient le barème utilisé lors d'une correction automatisée. À chaque test, on associe un certain nombre de point.
  • bareme_amc.csv : à la racine du dossier brouillons, un fichier qui contient le barème utilisé lors d'une correction à l'aide d'AMC. Ce fichier sera utilisé lors de la création d'un devoir.
• exercice.py : le fichier qui contient les solutions aux questions. Il permet tester la validité de l'énoncé et de ses tests. C'est cette phase qui est manquée par ceux qui composent les sujets de l'épreuve pratique.

À votre charge de :

• créer à la racine de brouillons, un fichier exercice_version_eleve.md qui serait un fichier prérempli à compléter par l'élève comme l'exercice 2 de l'épreuve pratique.
• d'ajouter les éventuelles images de votre document écrit dans le dossier latex, au format png ou jpg.

Le meilleur moyen de commencer, c'est de voir l'exemple. Il s'agit d'un exercice tiré d'un sujet de bac 2021.

Le principe est d'ajouter des informations au niveau des doctests. Les parties de code sont délimites par les trois tildes ~~~. Entre accolades, on rajoute les données qui seront prises en compte lors de la génération des divers fichiers. On détourne donc juste une possibilité qui existe déjà.

• .hidden : le contenu du code ne sera exporté vers aucun document élève ;
• .meta : ne sert qu'à classer les fichiers lors de le genèse d'un document prof utile pour chercher les exercices dans la base (pas en core fait - cela mérite réflexion !) Cette partie n'empêche pas le programme de fonctionner. On peut donc s'en passer pour l'instant.
• .python : sert à déclencher la coloration syntaxique de la version écrite ;
• .amc : le contenu, éventuellement vide, ne concerne que la version papier ;
• .test : le contenu sera exporté dans les fichiers de tests ;
• .all : correspond à .amc et .test ;
• file=Q_1.md : le nom du fichier test. Il faut qu'il corresponde au numéro de la question. Ici, c'est la question 1 de l'exercice. Utiliser des underscores et non des points. Bien sûr, pas d'espace ! Q_1_a.md pour la question 1.a. Ce nom servira également de label pour le fichier AMC.
• bareme=1 : le nombre de points associé à la question.

Il doit passer tous les tests. Cela permet de valider le sujet et sert de correction que l'on peut éventuellement montrer ensuite aux élèves.

gnsi brouillon --tester

Si tout se déroule sans accro, vous devriez voir les 2 barèmes s'afficher. gnsi transforme automatiquement les underscores en point pour le fichier AMC car en latex on ne peut les employer que dans un environnement mathématiques.

Bareme
Q_2.md, 1
Q_3.md, 1
Q_4.md, 1
Q_5.md, 1
Q_6.md, 1
Q_7.md, 1

Bareme AMC
Q.1, 1
Q.2, 1
Q.3, 1
Q.4, 1
Q.5, 1
Q.6, 1
Q.7, 1

Au premier lancement, il est généré la version élève de l'énoncé et la version latex. Si celle-ci existe, elles ne sont pas remplacées. Toutefois, si pour une raison ou une autre, vous voulez recréer ces 2 fichiers, vous pouvez lancer :

gnsi brouillon --tester --force

Attention, les 2 fichiers sont regénérés en même temps. Pour l'instant, je n'ai rien prévu pour traiter l'un indépendemment de l'autre.

L'export du format markdown au format n'est pas parfait. C'est pourquoi je retravaille toujours le fichier tex avant d'exporter. De toute façon, il faut en général gérer le format des images, s'il y en a.

Il existe également des problèmes dans la numérotation des questions. Si on veut éviter les travaux de numérotation trop importants, on peut éviter les sous-questions.

Pour visualiser le pdf, il suffit de lancer :

gnsi brouillon --pdf

gnsi brouillon --preparer

Cela permet de voir le nom de l'exercice et la version finale du pdf avec le nom de l'exercice.

Mettez au point exercice_version_eleve.md si ce n'est pas déjà fait. Ensuite :

gnsi brouillon --exporter

Tous les fichiers, sauf brouillon.tex sont recopiées dans un dossier exercice... dans le dossier exercices. En particulier, vous pouvez voir le pdf correspondant à l'exercice qui se trouve dans le dossier latex.

À terme, j'espère trouver le temps d'écrire une fonction qui collectent tous ces pdf en un seul fichier, le tout en les classant suivant informations contenues dans les balises .meta.

Si on souhaite corriger un exercice déjà exporté. On peut reprendre la procédure précédente après :

gnsi brouillon --clean
gnsi brouillon --corriger nom_de_l_exercice

nom_de_l_exercice est le nom du dossier dans exercices.

Parfois, on a déjà un sujet et le fichier python avec la correction.

Personnellement, j'utilise souvent pandoc pour convertir les fichiers à divers format. Pour les importer dans le dossier brouillon, il suffit de faire :

gnsi brouillon --importer fichier_markdown.md fichier_python.py [image1.png ...]

C'est un peu lourd mais pour l'instant il faut fournir les adresses absolues des fichiers. Le .md et le .py sont placés à la racine de brouillons et renommés exercice.md et exercice.py. Les fichiers .png, .jpg et .jpeg sont copiés dans le dossier latex mais pas renommés.

L'ordre n'importe pas, toutefois, il ne faut fournir qu'un seul fichier .md et/ou un seul fichier .py.

gnsi devoir -h

Il faut connaître les exercices que vous voulez insérer dans votre devoir.

Par exemple, la commande suivante :

gnsi devoir dm_t1_1 "Devoir maison 1" "NSI" "Année scolaire 2021-2022" exercice002 exercice003 exercice004

crée un devoir :

• qui sera rangé dans le dossier devoirs/dm_t1_1 ;
• dont le fichier latex aura pour titre Devoir maison 1, pour auteur NSI et pour date Année scolaire 2021-2022 ;
• composés des exercices exercice002, exercice003, exercice004.

Dans le dossier devoirs, le dossier suivant sera créé :

L'ordre des exercices lors de l'appel de la commande gnsi devoir impose la numérotation des exercices. Ainsi, dans l'exemple précédent, exercice002 apparaître sous le nom d'exercice_1, etc…

Quelques précisions supplémentaires :

• bareme.csv : le barème complet du devoir. Ce fichier sera utilisé pour la correction automatique ;
• setup.cfg : est une copie du fichier setup_devoir.cfg qui se trouve dans le dossier modeles. Pour la correction des devoirs, on effectuera toujours les tests avec nosetests3 mais on fera une sortie vers le fichier nosetests.xml ;
• bilans est le dossier où seront rangés les bilans individuels de élèves et le fichier prof ;
• docs contient tous les fichiers markdown qui servent de tests. gnsi s'est chargé de nommer correctement ces derniers. Vous pourriez voir par exemple exercice_1_Q_1.md.
• fichiers_eleves : toutes les versions élèves disponibles des exercices sont recopiées dans ce dossier. Bien sûr, les noms des fichiers ont été adaptés. Personnellement, je mets ces fichiers à disposition via Moodle.

• latex contient toutes les images des exercices ainsi que :

  • un fichier latex prêt à compiler dont le nom est le même que le devoir. Dans l'exemple précédent, on a un fichier dm_t_1_1.tex ;
  • un fichier latex prêt à être utilisé dans AMC. Dans l'exemple précédent, on a un fichier dm_t_1_1_amc.tex ;

  On peut donc retravailler la mise en page du document final. On ne peut toutefois pas changer l'ordre des exercices car ils ne correspondraient plus aux tests.

• travaux est le dossier où seront rangés les travaux élèves.

Vous l'aurez compris, j'utilise Moodle pour mettre le devoir à disposition des élèves. Ces derniers doivent déposer un fichier par exercice. Évidemment, exercice_1.py pour l'exercice 1.

Quand on ramasse le devoir, on veille à ce que la case indiquant que les travaux doivent ếtre rangés dans un dossier au nom de l'élève.

On récupère alors un dossier zip.

Il suffit d'écrire :

gnsi corriger devoir

Par exemple, après avoir ramassé les travaux du devoir dm_t1_1, il suffit de lancer :

gnsi corriger dm_t1_1

Dans le dossier bilans, on trouve :

• un fichier par élève au format markdown qui ressemble à :

---
title : Devoir maison 1
author : I****  A******
date : NSI
---

# Note : 18.57 / 20

## Exercice 1
- **test1** : 1 / 1
- **test2** : 2 / 2
- **test3** : 1 / 1

## Exercice 2
- **test1** : 1 / 1
- **test2** : 1 / 1
- **test3** : 2 / 2

## Exercice 3
- **Q.2** : 1 / 1
- **Q.3** : 0 / 1
- **Q.4** : 1 / 1
- **Q.5** : 1 / 1
- **Q.6** : 1 / 1
- **Q.7** : 1 / 1

# Détails erreurs

```{python}
Failed doctest test for exercice_3_Q_3.md
  File "/***********/GNSIcontenus/devoirs/dm_t1_1/docs/exercice_3_Q_3.md", line 0

----------------------------------------------------------------------
File "/***********/GNSIcontenus/devoirs/dm_t1_1/docs/exercice_3_Q_3.md", line 3, in exercice_3_Q_3.md
Failed example:
    finale(B)
Exception raised:
    Traceback (most recent call last):
      File "/usr/lib/python3.8/doctest.py", line 1336, in __run
        exec(compile(example.source, filename, "single",
      File "<doctest exercice_3_Q_3.md[1]>", line 1, in <module>
        finale(B)
      File "/***********/GNSIcontenus/devoirs/dm_t1_1/exercice_3.py", line 50, in finale
        return [racine(finale1,finale2)]
    TypeError: racine() takes 1 positional argument but 2 were given

```

• un fichier csv avec les résultats de tous les élèves de la classe. Personnellement, j'utilise ce fichier pour :
  • rentrer les notes dans le carnets de notes Moodle (importer un fichier csv lié par idmoodle -> nom de l'élève et note -> le devoir Moodle.)
  • envoyer les résultats individuellement grâce au module Mail Merge de Thunderbird

Comme indiqué dans l'introduction de ce tutoriel, on peut utiliser le programme python copydetect pour avoir une idée des élèves qui se sont inspirés mutuellement.

Par exemple, pour le devoir précédent, il m'a suffit de lancer :

copydetect -t /*********/GNSIcontenus/devoirs/dm_t1_1/travaux/ -b /**********/GNSIcontenus/devoirs/dm_t1_1/fichiers_eleves/ -e py -l -T -s

Chaque fichier est comparé à tous les autres et on obtient un rapport html avec les fichiers les plus ressemblants. C'est très instructif.