Rédaction des fiches de TD et TP

Contenu

Rédaction des fiches de TD et TP#

Renouveler les fiches: en quoi cela consiste?#

Rechercher dans les sources des fiches de TD et TP si nous nous étions mis des choses à faire (« TODO »); si oui les traiter dans la mesure du possible;
Lorsqu’elles manquent, rajouter des solutions (voir ci-dessous)
Relire les fiches de TD et TP (dont les feuilles Jupyter) pour toute typo. Que ce soit pour les fiches TD et TP ou pour les fiches Jupyter, relire aussi bien la version étudiants que la version enseignants pour éviter les bugs.
Avant d’envoyer l’énoncé de TD à la reprographie, vérifier comment tombent les sauts de pages dans le PDF, et ajuster le cas échéant en insérant certaines des commandes suivantes :
```
{raw:latex}`\clearpage`
{raw:latex}`\enlargethispage{2cm}`
{raw:latex}`\bigskip`
```
En particulier, si le PDF déborde un peu d’un nombre pair de pages, cela vaut le coup d’y passer un peu de temps pour gagner la page de débordement. Une feuille de plus dans le sujet, c’est une ramette de 250 feuilles de consommée!
Et puis les idées d’améliorations sont bienvenues!

Timing#

En début de la semaine précédente: contactez Nicolas et le relecteur pour confirmer que l’on est dessus.
Faire le maximum;
Venir en amphi le lundi;
Voir à la fin de l’amphi avec Nicolas pour les points éventuels qui nécessitent discussion;
Finir la fiche de TD mercredi soir pour relecture jeudi ou vendredi matin tôt et envoi à la repro dans la foulée (attention, vérifier la dispo des relecteurs et voir avec eux quand le sujet doit être terminé);
Finir la fiche de TP dimanche (ou avant…) pour relecture lundi.

Conventions d’écriture#

Textes#

En dehors des examens qui sont encore en LaTeX, tous les textes (feuilles Jupyter, de TP, de TD, page web, …) sont maintenant rédigés avec une variante de Markdown appelée Myst. Voir ce guide.

Ci-dessous, quelques conventions d’écriture; elles ne sont pas encore appliquées systématiquement, mais c’est ce vers quoi nous tendons progressivement :

Insérer un espace insécable devant les :.
À terme, on les supprimera quand ils seront gérés automatiquement par le moteur de rendu, comme c’est le cas avec LaTeX.
Pas de majuscule après :.
Instructions aux étudiants : utiliser l’impératif pluriel : «lancez Jupyter», «compilez votre programme». Pour mettre en valeur les instructions dans les exercices, les mettre dans des listes à puces numérotée.
Exercices trèfle : dans les feuilles de TD, utiliser \(\clubsuit\) (contrainte de compatibilité pour compiler avec LaTeX). Partout ailleurs, utiliser le caractère unicode ♣. En cours de standardisation: mettre ♣ à la fin du titre ligne, comme dans Exercice 3 : bla bla ♣. Pour un item d’un exercice
MyST permet d’écrire des encarts, et sous peu permettra de définir des encarts dédiés (comme les newtheorem ou newenvironment de LaTeX). En attendant standardiser les encarts comme suit :

Définition: Blas

Un bla est un …

Syntaxe : bla

bla bla bla

Sémantique : bla

bla bla bla

Astuce

Indication

Exercice

bla bla bla

Indication

Bonne pratique bla bla bla

À terme, il y aura des encarts dédiés.

Caveat : il n’est pas encore possible d’avoir des encarts couvrant plusieurs cellules (et donc en particulier avec du code). En attendant, contourner en répétant l’encart dans chaque cellule de texte, avec un titre vide hors la première.
Lorsqu’un concept est introduit, le marquer avec :
```
Un {definiendum}`bla`
```
Cela assure un rendu homogène, le mot est ajouté dans l’index, sa traduction (si définie dans le fichier ./_config.yml` est affichée), et enfin la sémantique pourra être utilisée ailleurs, etc.

Si une forme différente du terme défini est utilisée (pluriel, conjugaison, définition informelle), utiliser à la place:
```
Un {definiendum}`Programmes <programme (informel)>`
```

Rédaction des solutions#

Les solutions s’écrivent dans les sources *.md dans un environnement. S’il s’agit de texte (dans une cellule en markdown) on écrit ceci dans la cellule :

BEGIN SOLUTION
la solution ici
...
END SOLUTION

S’il s’agit de code dans une cellule Jupyter, on écrit :

/// BEGIN SOLUTION
...
/// FIN SOLUTION

La syntaxe ci-dessus est similaire pour les fichiers .cpp qui peuvent être importés dans les sujets.

Le code doit être compilé et testé au préalable, et indenté suivant les conventions du cours (voir conventions-codage.md).

Certaines fiches utilisent encore de vieilles syntaxes :

///Correction
...
///FinCorrection

ou :

int f(...) {///Correction
    ...
}

Voir les solutions déjà faites pour des exemples.

Un fichier qui n’a pas vocation à être dans l’archive fournie aux étudiants (typiquement une solution) doit être signalé par un nom de fichier en *-correction.*.

Rédaction des feuilles Jupyter#

À propos#

nbgrader est un outil pour (partiellement) automatiser la collection et la correction de feuilles Jupyter. Le modèle est très simple: on marque certaines cellules comme contenant des tests; si elles déclenchent une erreur, des points sont enlevés.

Chaque année, nous élargissons un peu la mise en place de nbgrader. Pour le moment, cela donne un score automatique qui sert d’indication d’avancement aux étudiants. Les enseignants peuvent aussi s’en servir comme un indicateur parmi d’autres pour l’attribution des notes de TP.

Édition des feuilles avec Jupyter#

Tout d’abord, il est recommandé de travailler dans l’environnement info-111. Le plus simple est de travailler sur le serveur JupyterHub. Sinon vous pouvez installer les logiciels requis et vous plaer dans l’environnement info-111 avec la commande :

    source activate info-111

Lancez Jupyter, naviguer dans le sous-dossier de la semaine correspondante, et ouvrez la feuille à éditer. Pour afficher les options d’éditions de nbgrader, cliquez dans la colonne à droite du notebook sur Create Assignment. Dans ce même menu, vous avez aussi moyen d’afficher toutes les méta données de la cellule.

Attention, lorsqu’on avance dans la feuille Jupyter, le menu de droite ne suit pas toujours automatiquement. Notez que les données correspondant à la cellule active ont un petit liseret bleu (comme la cellule elle-même)

Il y a six catégories de cellules :

Les cellules de texte énoncé : elles sont à passer en read-only pour éviter que les étudiants ne modifient l’énoncé;
Les cellules de code énoncé : ce sont les cellules d’exemples de code que l’on ne veut pas voir modifiées par les étudiants, à mettre en read-only également;
Les cellules de question en français : ce sont les cellules de texte qui nécessitent une réponse écrite de la part des étudiants. Elles sont à mettre en mode Manually graded answer (mettre 1 point à la question dans le doute). La solution à la question est à mettre entre des balises « BEGIN SOLUTION » et « END SOLUTION », chacune sur sa ligne;
Les cellules de question de code : ce sont les cellules qui doivent être complétées par les étudiants par du code. Elles sont à mettre en mode Autograded answer. Mettre la solution entre balises « /// BEGIN SOLUTION » et « /// END SOLUTION »; on peut fournir aux étudiants un squelette à trous en ne mettant que certaines parties entre ces balises.
Les cellules de tests : ce sont les cellules qui vérifient que les solutions des étudiants donnent de bons résultats en utilisant CHECK. La cellule est à mettre en mode Autograder tests (mettre 1 point à la question dans le doute). On peut rajouter des tests qui seront cachés aux étudiants mais qui compteront dans la correction automatique, entre des balises « // BEGIN HIDDEN TESTS » et « // END HIDDEN TESTS ». Mettre préférablement chaque CHECK dans une cellule séparée.
Les cellules libres : typiquement, ce sont des cellules pour que les étudiants puissent tester leurs fonctions et donc ils doivent pouvoir les modifier. Ces cellules sont à laisser en mode « -« .

Pour un exemple de ces six catégories, voir la feuille 1 du TP 4.

Pour plus de détails, voir aussi la documentation de nbgrader

Relecture et version étudiant#

Avant de continuer, assurez vous que la feuille contenant la correction fonctionne bien, par exemple en redémarrant le noyau et en faisant Cellule->Exécuter tout.

Si tout marche bien, il est temps de vérifier que la version que recevront les étudiants est correcte. Pour se faire, se placer dans le dossier Info111 du dépôt git (toujours dans l’environnement de développement info-111), et exécuter la commande suivante (à adapter en fonction de la semaine):

make assignments Assignments=Semaine4

Une fois la commande exécutée, naviguez dans le dossier _build/Semaine4 : vous devriez y trouver les versions destinées aux étudiants des feuilles Jupyter. Vérifiez ces feuilles (notamment que les solutions sont bien retirées) dans Jupyter.

Lorsque les modifications sont terminées, enregistrez et poussez sur le dépôt git les feuilles version «enseignant» qui sont dans le dossier Semaine4, et prévenez Nicolas qui s’occupera de publier le tout.