fiches.md

# 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
  jouant avec `\clearpage`, `\enlargethispage{2cm}`, `\bigskip`, etc.
  En particulier, si le PDF déborde un peu d'un nombre paire 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
  400 feuilles de consommée!

- Et puis les idées d'améliorations sont bienvenues!

## Timing

- En début de la semaine précédente: contacter Nicolas et le relecteur
  pour confirmer que l'on est dessus.

- Faire le maximum;

- Venir en amphi le jeudi;

- Voir à la fin de l'amphi avec Nicolas pour les points éventuels qui
  nécessitent discussion;

- Finir la fiche de TD jeudi soir pour relecture vendredi matin tôt et
  envoi à la repro dans la foulée (autant que possible);

- Finir la fiche de TP dimanche pour relecture lundi.

## Rédaction des solutions

Les solutions s'écrivent dans les sources TD.tex ou TP.tex dans un
environnement \begin{correction} \end{correction}. S'il s'agit de
code, il doit être importé depuis un fichier .cpp qui doit être
compilé et testé au préalable, et indenté suivant les conventions du
cours (voir [conventions-codage.md]()). Il est possible et même recommandé
d'utiliser les mêmes fichiers .cpp pour le sujet et la solution, en
annotant les parties à cacher dans le sujet avec:

    ///Correction
    ...
    ///FinCorrection

Même chose dans les feuilles Jupyter avec:

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

(/// non requis dans les cellules de texte)

Cette dernière syntaxe est celle utilisée par l'outil de correction
automatique nbgrader; en 2019, on uniformisera tout vers cette
syntaxe.

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.*`.

## Utilisation de nbgrader

[nbgrader](https://nbgrader.readthedocs.io/) 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.

Cette année nous élargissons la mise en place de nbgrader. Il sera
probablement trop tôt pour l'utiliser systématiquement. Mais les
chargés de TP pourront se servir des fiches rendues et des notes
calculées comme d'indications pour l'attribution des notes de TP.

### Rédaction des fiches

Tout d'abord, il est recommandé de travailler dans l'environnement
info-111 en suivant le [tuto d'installation](logiciels/jupyter-installation.md)
et en se plaçant dans l'environnement info-111 avec la commande :

        source activate info-111

Vous pouvez aussi travailler sur le [serveur JupyterHub](http://jupytercloud.lal.in2p3.fr/).

Lancer Jupyter, naviguer dans le sous-dossier de la semaine correspondante,
et ouvrir la feuille à éditer. Si nbgrader est déjà activé, vous verrez un
menu déroulant à droite de chaque cellule. Si ce n'est pas le cas, aller dans
`Affichage -> Barre d'outil de cellule -> Create Assignment` ce qui fera apparaître
le menu déroulant. Celui-ci permet de spécifier la nature des cellules, d'en modifier
les propriétés. 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
   `ASSERT`. 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 ASSERT
   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 6 catégories, voir la feuille 1 du TP 4.

Pour plus de détails, voir aussi la [documentation de nbgrader](https://nbgrader.readthedocs.io/en/stable/user_guide/creating_and_grading_assignments.html#developing-assignments-with-the-assignment-toolbar)

### Relecture et version étudiant

Avant de continuer, s'assurer que la feuille contenant la correction fonctionne bien, par exemple en redémarrant le kernel 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):

        nbgrader assign --create --force Semaine4

Une fois la commande exécutée, naviguer dans le dossier `_build/Semaine4` : vous devriez y trouver les versions destinées aux étudiants des feuilles Jupyter. Vérifier 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`. La version «étudiants» sera générée
automatiquement lors de la création de l'archive `.zip` de la semaine.