Conventions d’écritures#
À propos
Les conventions d’écriture ci-dessous sont une tentative d’homogénéisation des usages qui ont émergé après multiples expérimentations avec JupyterBook, MyST, JupyterLab-Myst, etc. dans des cours à Orsay avec de grandes cohortes, dont :
C’est une première proposition qui a vocation a être discutée point par point. Retours bienvenus!
Formatage#
On utilise la syntaxe Markdown avec son extension MyST.
On utilise mdformat et son extension mdformat-myst pour standardiser le formatage.
Les lignes sont repliées avec une largeur de texte de 89 colonnes.
On utilise
\pour forcer un saut de ligne plutôt qu’un double espace en fin de ligne.~~On indente systématiquement de quatre espaces, y compris dans les listes à puces, etc.~~
Attention
mdformat ne supporte pas l’indentation des listes à quatre espaces.
Attention
Même avec l’extension mdformat-myst, mdformat ne semble actuellement pas respecter les
encarts marqués avec :::. On se contente donc, pour le moment, des encarts délimités
par ```.
À discuter
Pour les listes à puces numérotées, il est possible de laisser le moteur de rendu numéroter automatiquement les puces en écrivant :
1. bla
1. bla bla
1. bla bla bla
Cas particulier : lorsqu’une liste à puces s’étend sur plusieurs cellules – typiquement dans des diapos ou des exercices – la numérotation automatique dans JupyterLab-MyST reprend la numérotation à 1 dans chaque cellule ce qui n’est pas souhaitable. On peut forcer la numérotation à reprendre à une valeur ultérieure :
3. bla
3. bla bla
3. bla bla bla
Souhaitons-nous forcer cette convention, notamment dans le reformatage avec mdformat?
Opinion de NT: au vu du point ci-dessus, recommander la convention, mais sans la forcer
avec mdformat.
À discuter
NT: je ne suis pas convaincu par la convention de mdformat de systématiquement insérer un saut de ligne entre chaque puce, même sur des listes simples. Cela gaspille de l’espace vertical.
Typographie pour les documents en français#
Les majuscules sont accentuées.
En attendant que, comme LaTeX, MyST gère automatiquement l’affichage d’un espace fine
insécable avant les :, on le fait approximativement à la main: chaque : est précédé
dans les sources par un espace insécable comme dans :. Si le clavier ne permet pas
d’insérer facilement un tel espace, on se contentera d’un espace normal: : en
attendant un correctif systématique par recherche et remplacement. En revanche
(approximation aussi), on ne met pas d’espace avant !, ?, ;, etc.
Todo
Écriture des nombres en toutes lettres lorsque … + ref
Voir le lexique des règles typographiques en usage à l’imprimerie nationale.
Annotations de difficulté#
Un ♣ en début de phrase ou de titre indique une activité (exercice, information) pour
aller plus loin qu’il n’est pas nécessaire de maîtriser pour passer à la suite.
```{admonition} Exercice : ♣ lorem ipsum
```
1. ♣ Calculez ...
Textes#
Les textes, y compris dans les encarts comme les définitions, sont prévus pour être lus en autonomie (contrairement aux notes de cours d’Info111 ou ISD qui sont prévues comme des diapos). On utilisera donc préférentiellement des phrases complètes, des paragraphes, des mots de transition, pour donner une certaine rondeur à la lecture.
Le texte s’adresse au lecteur ou la lectrice à la deuxième personne, en vouvoyant en Français. On peut aussi utiliser la première personne du pluriel.
Le texte vise à être inclusif; autant que possible en utilisant des formulations non genrées; sinon avec écriture alternativement féminine et masculine, ou inclusive.
Terminologie#
Pour les terminologies techniques, on s’attache à utiliser la langue du texte. Par exemple, si le texte est en français, on minimise le franglais et les angliscimes: «renvoyer» plutôt que «retourner»; «feuille» ou «fiche» plutôt que notebook.
On utilise chaque fois que possible le vocabulaire du cours, comme autant d’occasions de l’ancrer dans la mémoire.
Exemple
«Définissez la fonction spécifiée ci-dessous» plutôt que «écrivez» ou «implantez». Variante: documentée plutôt que spécifiée si la fonction l’est par une doc.
Lorsque l’on parle de logiciel, de technologie, on s’attache à nommer la fonction plutôt que la marque: «faire une recherche sur internet» plutôt que «google»; «traitement de texte» plutôt que «word»; «assistant conversationnel» plutôt que «chat-GPT».
À discuter
Quel nom adopter pour une feuille Jupyter? feuille? fiche? carnet? calepin? «Calepin» est le plus sympathique, mais comme «carnet» ou «notebook» est impropre: un calepin une collection de feuilles plutôt qu’une seule.
Accessibilité et portabilité#
Globalement, JupyterLab et MyST s’en sortent plutôt bien en terme d’accessibilité, dès lors que l’on mets l’accent sur le fond plutôt que sur la forme :
Utiliser en priorité les fonctionalités natives de Markdown/MyST (encarts, …) plutôt qu’introduire du HTML de rendu.
Être rigoureux sur le découpage en sections (exemple: pas de saut de
#à###)Annoter systématiquement les figures avec une description alternative.
```{figure} bla.png :alt: Une image d'un bla en pleine action ```
Attention
Quel équivalent pour les knowls / hover-cards / hover-boxes sur les téléphones portables?
Code#
On suit les conventions PEP8.
Dans un document en Français, les noms de variables, fonctions, classes spécifiques au document sont en français, avec accents.
À discuter
Quelle convention pour les documents multilingues?
Attention
Mettre les accents dans le code est un choix discutable. Mais Python 3 gère très bien les accents dans le code et ailleurs, alors autant en profiter pour écrire du français correct. Il faudra juste voir si, en pratique, cela peut poser des difficultés aux apprenants pour saisir ces accents.
Les noms sont en une lettre lorsque cela colle avec des notations mathématiques ou physiques courantes. Sinon des mots complets, en Camel Case pour les noms de classes et minuscule séparés par des
_pour des noms de fonctions et variables.À discuter
Pour les compteurs de lignes et de colonnes dans un tableau 2D:
i,j? ouligne,colonne?Si pertinent, on pourra utiliser des lettres grecques et autres symboles mathématiques. Il faudra juste montrer comment les saisir interactivement avec
\alpha.
Méta informations#
Notes aux enseignants#
```{admonition} Notes aux enseignants
```
Objectifs pédagogiques#
```{admonition} Objectifs pédagogiques
Décrire les compétences qui seront travaillées. Penser implicitement: «l'étudiant est capable de ...».
```
Choses à faire#
```{todo} Résumé en une ligne
Description détaillée
```
Annotations sémantiques#
Outre les éléments narratifs ci-dessus, nous visons d’annoter tous les documents (voire à terme des fragments de ceux-ci) par des métadonnées comme suit. Cela permettra de raisonner automatiquement sur le matériel pédagogique, notamment pour faire de l’enseignement adaptatif.
---
learning:
objectives:
understand: expression booléenne
prerequisite:
apply: [variable, affectation]
---
Les clés sont: discover (activité de découverte d’une notion avant de l’avoir définie
formellement), know (connaître la définition; typiquement testé par flashcard),
understand (savoir reconnaître et interpréter; exercices d’application immédiate),
apply (savoir utiliser). Les valeurs sont des noms de notions, ou listes de tels noms.
La liste des noms de notions (à compléter!) est dans le fichier _config.yml. Ces
notions incluent aussi des éléments pédagogiques tels que des difficultés typiques telles
que «afficher versus renvoyer». On essaye de nommer ces difficultés de façon positive (ce
que l’étudiant doit comprendre): «afficher versus renvoyer» plutôt que «confusion entre
afficher et renvoyer». À voir comment on traite les idées fausses (misconceptions).
À terme, on pourra envisager, dans les cas simples, de générer automatiquement une version narrative à partir de ces métadonnées. Pour le moment, et pour gagner de l’expérience, on peut aussi inclure une version narrative si certains éléments ne s’expriment pas bien sous forme de métadonnées quitte à ce que ce soit un peu redondant.
Citations#
Lorsque l’on récupère ou s’inspire d’une ressource, on la cite avec le mécanisme de citation de MyST avec, autant que possible, une url pointant précisément sur le fragment réutilisé.
```{admonition} Remerciements
Ce document est tiré de / inspiré de @...
```
Encarts#
MyST permet de marquer des encarts (admonitions) comme dans l’exemple ci-dessus pour les remerciements. Ce sont l’équivalent des environnements en LaTeX.
Attention
L’implémentation des encarts – dans Jupyter-Book, MySTmd, JupyterLab-MyST, ou md-format-MyST – n’est pas encore uniforme et complète, notamment pour l’internationalisation et la définition d’encarts personnalisés. Une partie des conventions décrites dans cette section résulte d’un compromis pour un rendu raisonnable dans toutes les cas.
Encarts divers#
En anglais, on dispose des
encarts prédéfinis
hint, tip, seealso, etc. Par exemple, l’encart suivant:
```{hint}
In English, we may use predefined admonitions such as `hint`, `tip`, ...
```
est rendu comme suit:
Hint
In English, we may use predefined admonitions such as hint, tip, …
Certains encarts prédéfinis comme attention, danger, important, note ne
nécessitent pas de traduction et peuvent donc être utilisés en Français aussi.
Dans les autres cas , on utilise une directive admonition avec un titre, et
éventuellement une classe :
```{admonition} Exemple
```
Apartés, rappels, remarques, pour aller plus loin :
```{admonition} Apparté: Lorem ipsum
:class: hint
```
```{admonition} Les machins en Python
:class: hint
```
Astuces, indications, …
```{admonition} Astuce
:class: tip
```
Voir aussi, références, …
```{seealso} Voir aussi
...
```
Lorsque l’on utilisera MyST ou JupyterBook 2, on pourra utiliser une version plus courte :
```{hint} Aparté ...
```
On peut utiliser la classe dropdown pour replier l’encart par défaut; typiquement pour
des indications supplémentaires à ne consulter que si l’on ne voit pas comment s’y
prendre.
```{admonition} Indication
:class: tip dropdown
```
À terme, on voudra avoir une collection d’encarts nommés prédéfinis, pour pouvoir configurer leur rendu une bonne fois pour toutes, comme dans LaTeX. C’est déjà possible de définir de tels encarts avec JupyterBook et MySTmd, mais sans qu’ils soient gérés en usage interactif avec JupyterLab-Myst :
```{apparté} Lorem ipsum
```
Si un titre d’encart est donné en plus du type d’encart (comme dans
```{admonition} Astuce: Lorem ispum), le titre commence par une majuscule.
Attention
Ce point est discutable vis-à-vis des conventions typographies française qui ne mettent
normalement pas de majuscules après un :. Mais cela permettra une transition facile
vers des encarts nommés ````{astuce} Lorem ipsumoù la séparation entre type d'encart et titre sera assurée par autre chose qu'un:`; c’est aussi la convention qui se trouve
avoir été la plus suivi dans les cours existants :-)
Définitions#
(bidule)=
```{admonition} Définition : Bidule
Un {definiendum}`bidule` ...
```
Le rôle definiendum indique le concept qui est défini, ainsi que le label avec lequel
référencer ce concept. Si le concept et le label diffèrent (par exemple pour des
questions d’accord), on peut utiliser :
Les {definiendum}`bidules <bidule>` ...
Le label peut contenir des espaces, des accents. Pour référencer la définition, on
utilise un «slug» obtenu en remplaçant les lettres accentuées par les lettres non
accentuées correspondantes et les espaces par des _.
Motivation
Cette annotation sémantique les définitions permet une mise en exergue systématique dans la version étudiant des carnets et la version HTML, de construire un index sur la page web, et – dans un certain nombre de cas – de faire apparaître la définition dans un hover card quand on passe la souris sur un lien vers le mot.
À terme elle permettra de générer des flashcards pour des révisions, etc.
Todo
Implanter le rôle definiendum sur py-edu-fr.
Définitions avec encarts Syntaxe et Sémantique:
````{admonition} Définition: Foo
Lorem ipsum dolor ...
```{admonition} Syntaxe
...
```
```{admonition} Sémantique
```
````
Todo
Tableaux résumés de listes d’opérations?
Exercices#
En anglais, on peut utiliser les encarts standards pour les exercices, ainsi que leurs variantes pouvant porter sur plusieurs cellules.
Ces encarts ne sont pas encore internationalisés. Du coup, en Français, on utilise un
encart manuel Exercice.
Chaque action est un item d’un enumerate. On utilise l’impératif.
```{admonition} Exercice
1. Faites blah blah blah
2. Exécutez blah blah bla
```
Il est bon de mettre un titre à l’exercice, et de numéroter les exercices dans une feuille (en attendant que ce soit fait automatiquement).
```{admonition} Exercice 3 : lorem ipsum
...
```
MyST dans un carnet Jupyter ne permet pas (encore) de réaliser des encarts manuels sur plusieurs cellules. Ce serait pourtant bien utile pour pouvoir, par exemple, inclure des cellules de code dans un exercice, ou pour faire des diapos où le contenu de l’encart apparaît en plusieurs itérations. Pour le moment, on utilise en Français l’approximation suivante :
```{admonition} Exercice
...
```
puis dans les cellules de texte suivantes:
```{admonition}
...
```
voir par exemple:
Attention
Une «admonition» sans titre est un abus de la syntaxe MyST; tous les outils ne la gère pas bien. On fait avec pour l’instant …
Solutions; version étudiant versus version instructeur#
Les documents rédigés ici sont à destination des instructeurs. La version distribuée aux étudiants est généré automatiquement grâce aux conventions décrites brièvement ci-dessous, en supprimant les notes aux enseignants, les solutions, en verrouillant certaines cellules, etc. Pour cela on utilise travo-prepare qui suit et étends les conventions de nbgrader (à discuter et configurer pour py-edu-fr).
De même, sur la page web, les notes aux enseignants, les todos, et les solutions peuvent être cachées par défaut, ou supprimées (à discuter et configurer pour py-edu-fr).
Solutions#
Pour délimiter une solution de référence, notamment pour produire des textes ou codes à
trous (multiples) que l’étudiant.e doit compléter, on insère une ligne contenant le
marqueur BEGIN SOLUTION (resp. END SOLUTION) pour indiquer le début (resp. la fin) de
la solution.
def factorielle(n):
if n == 0:
### BEGIN SOLUTION
return 1
### END SOLUTION
else:
### BEGIN SOLUTION
return n * factorielle(n-1)
### END SOLUTION
Les lignes avec les marqueurs de début et de fin doivent être indentées de façon identique et cohérente avec le contexte.
Pour des réponses dans les cellules markdown, on mets des sauts de ligne avant et après les marqueurs pour un meilleur rendu :
1. Décrivez bla bla bla
BEGIN SOLUTION
bla bla bla
END SOLUTION
Pour des solutions que l’on souhaite inclure dans la feuille de l’étudiant, on pourra utiliser alternativement un encart «Solution», replié ou pas par défaut :
```{admonition} Solution
:class: dropdown
```
À terme, lorsque JupyterLab-MyST donnera un rendu satisfaisant, on pourra utiliser l’encart standard :
```{solution}
...
```
Métadonnées de cellule; correction et rétroaction automatique#
Pour chaque cellule, on peut définir (dans l’onglet Create Assignment de la barre de
droite) un type : lecture seule, cellule autocorrigée, cellule de test. Pour ces
dernières, on peut associer des points: si la cellule s’exécute sans exception,
l’étudiant reçoit les points indiqués, sinon non. (cf dépôt de cours info 111).
Alternativement, on peut utiliser des tags, ce qui donne des métadonnées plus concises. Voir la documentation de prepare pour les détails.
Exercices Jupylates#
Voir la documentation de Jupylates.
Comment choisir la classe?
hintpour donner à réfléchirtippour suggérer des actionsseealsopour renvoyer à des information ailleurs