# Conventions d'écritures ```{admonition} À 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 : - [Info111: Introduction à la Programmation Impérative](https://nicolas.thiery.name/Enseignement/Info111/) - [Introduction à la Science des Données](https://nicolas.thiery.name/Enseignement/IntroScienceDonnees/) - [Introduction à la programmation, avec Python et Jupyter](https://introductionprogrammationpython.pages.centralesupelec.fr/) C'est une première proposition qui a vocation a être discutée point par point. Retours bienvenus! ``` ## Format Le matériel pédagogique ainsi que cette page web sont rédigés [Markdown](https://fr.wikipedia.org/wiki/Markdown), avec son extension [MyST](https://mystmd.org/guide/typography); cette extension offre de nombreuses facilités pour la rédaction de documents scientifiques, et plus généralement de textes structurés (ST: *Structured Text*): encarts, références croisées, citations, etc. Une partie du matériel pédagogique est composé de [fiches Jupyter](https://jupyter.org/notebook) permettant d'alterner narration, calcul, visualisation, programmation et interactions. Ces fiches sont aussi au format Markdown+MyST, grâce à l'extension Jupytext, plutôt qu'au format natif (.ipynb) de Jupyter. Ce choix permet d'éditer ces fiches au choix avec Jupyter ou un simple éditeur de texte, facilite la gestion de version, et évite d'enregistrer l'état d'exécution des calculs (résultats, ...). Pour standardiser le formatage des fiches, on utilise [mdformat](https://mdformat.readthedocs.io/) et les conventions suivantes: - 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 privilégiera `:::` pour les encarts contenant du texte en Markdown et \`\`\` pour les encarts de code. En effet, les encarts utilisant `:::` sont formatés en tant que code Markdown alors que ceux utilisant \`\`\` ne le sont pas. - On indente systématiquement de deux espaces, y compris dans les listes à puces. :::{attention} `mdformat` et son extension `mdformat-myst` ont à ce jour quelques limitations : - pas de support pour les encarts marqués avec `:::`. - ligne vide en trop après les labels `(label)=` - écriture verbeuse des métadonnées incompatible avec `jupytext`. - indentation dans les listes à puces forcée à deux espaces. Aussi, on utilise (temporairement?) `mdformat-py-edu-fr`, une commande développée spécialement pour le projet () utilisant une [version modifiée](https://github.com/nthiery/mdformat-myst) de l'extension [mdformat-myst](https://github.com/executablebooks/mdformat-myst) et un post-traitement basé sur Jupytext. En pratique, la commande `mdformat-py-edu-fr` est installée automatiquement par PDM et les contributeurs n'ont qu'à exécuter `make format`. Noter que les encars ```` ```{code-cell} ```` sont formatés avec `ruff format`, sauf si l'on rajoute au début `:format: false`. ::: ### Listes à puces Pour les listes à puces numérotées, il est possible de laisser le moteur de rendu numéroter automatiquement les puces en écrivant : ```markdown 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 : ```markdown 3. bla 3. bla bla 3. bla bla bla ``` Décision: pour faciliter la lecture du texte brute, on numérote à la main les puces. ```{admonition} À 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 Référence: [lexique des règles typographiques en usage à l'imprimerie nationale](https://fr.wikipedia.org/wiki/Lexique_des_r%C3%A8gles_typographiques_en_usage_%C3%A0_l%27Imprimerie_nationale). Les majuscules sont accentuées. À terme, MyST gérera automatiquement la typographie de l'espacement autour des signes de ponctuation, tels que les espaces fine insécable autour des ponctuations comme `:`. En prévision de cela, la convention dans les sources est donc, comme en LaTeX, de ne pas mettre d'espace devant les ponctuations `:`, `!`, `?`, `;`, et de les faire suivre d'un espace, comme suit: `lorem: ipsum`. À titre d'exception, un auteur peut choisir de faire une approximation en précédant chaque `:` dans les sources par un espace insécable comme dans ` :`. De même, on colle les guillemets `«` et `»` au texte qu'ils entourent. ```{admonition} Écriture des nombres Voir les [recommandations de la Wikipédia](https://fr.wikipedia.org/wiki/Wikip%C3%A9dia:Conventions_typographiques#Principes), dont les éléments principaux sont : - Il est recommandé d’écrire les nombres à un seul chiffre en toutes lettres («au long»); par exemple, «au bout de deux ans d’existence» plutôt que «au bout de 2 ans d’existence». - En règle générale, les nombres sont écrits de préférence «au long» lorsqu’ils indiquent des grandeurs — deux cents mètres, trois mille habitants, quinze francs… — sauf lorsque leur profusion les rendrait difficilement lisibles. ``` ## 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. ```markdown :::{admonition} Exercice : ♣ lorem ipsum ... ::: :::{admonition} Exercice 1. Lorem Ipsum ... 2. ♣ 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 double (étudiantes et étudiant) ou alternativement féminine et masculine. Afin de suivre les recommandations d'accessibilité (todo: ref), on évite l'écriture inclusive avec un point médiant. ## 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. ```{admonition} 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». ```{admonition} Fiche Chaque document individuel est nommée "fiche". Les alternatives classiques, sont feuille, carnet, calepin, notebook. «Calepin» est le plus sympathique, mais comme «carnet» ou «notebook» est impropre : un calepin une collection de fiches plutôt qu'une fiche individuelle. ``` ## Transitions et navigation Chaque fiche commence par une introduction en quelques mots décrivant ce que le lecteur va y faire et apprendre, et se termine par une conclusion similaire. La conclusion peut proposer des pistes pour aller plus loin. Cependant, sauf lorsque plusieurs fiches forment un tout qui s'enchaîne fortement, on évite de mettre des liens vers la fiche suivante / précédente : cela facilite en effet la réorganisation d'un parcours pédagogique, et la réutilisation des fiches entre parcours pédagogiques. De tels liens sont rajoutés automatiquement en fonction de la façon dont les fiches s'enchaînent dans le parcours pédagogique. ## 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. ```markdown :::{figure} bla.png :alt: Une image d'un bla en pleine action ::: ``` :::{attention} Quel équivalent pour les [knowls / hover-cards / hover-boxes](https://en.wikipedia.org/wiki/Hoverbox) sur les téléphones portables? ::: ## Code - On suit les conventions PEP8. - En général, le code est en anglais. À voir si l'on souhaite faire une exception pour les toutes premières feuilles d'introduction, notamment celles qui pourraient être réutilisées au lycée ou collège. :::{admonition} À discuter :class: attention 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. :::{admonition} À discuter Pour les compteurs de lignes et de colonnes dans un tableau 2D: `i`, `j`? ou `ligne`, `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 ```markdown :::{admonition} Notes aux enseignants ... ::: ``` ### Objectifs pédagogiques ::::markdown :::{admonition} Objectifs pédagogiques Décrire les compétences qui seront travaillées. Penser implicitement: «l'étudiant est capable de ...». ::: :::: ### Choses à faire ```markdown :::{todo} Résumé en une ligne Description détaillée ::: ``` (ontology)= ### Annotations sémantiques et ontologie 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. ```yaml --- learning: objectives: understand: expression booléenne prerequisite: apply: [variable, affectation] --- ``` Les clés sont: - `discover`: être préparé mentalement à l'introduction formelle d'une notion; typiquement par des motivations, l'étude d'exemples, une définition intuitive, etc. - `know` (connaître): connaître la définition; typiquement testé par flashcard; - `understand` (compréhension): être capable de reconnaître et interpréter (un savoir); typiquement testé par des exercices d'application immédiate; - `apply` (application): être capable d'appliquer (un savoir-faire). ```{todo} Rename `know` by `remember`, according to https://en.wikipedia.org/wiki/Bloom%27s_taxonomy . ``` Les valeurs sont des noms de notions, ou listes de tels noms. La liste des noms de notions (à compléter!) est dans le fichier `ontology.yml`. Ces notions incluent aussi des éléments pédagogiques comme 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 traiter les idées fausses (*misconceptions*). ```{admonition} Lien avec la taxonomie de Bloom :class: hint dropdown Les trois clés `know`, `understand`, `apply` correspondent aux trois premiers niveaux de la [taxonomie de Bloom](https://fr.wikipedia.org/wiki/Taxonomie_de_Bloom). Il serait possible d'inclure les niveaux supérieurs de cette taxonomie, mais la pratique d'annotation semble indiquer qu'ils sont peu pertinents pour les ressources pédagogiques concernées. En revanche, cette même pratique a suggéré l'ajout du niveau préalable `discover`. Cette déviation doit être discuté avec des spécialiste de l'éducation; elle pourrait être spécifique à l'annotation de micro activités (à l'échelle d'un exercice), alors que la taxonomie de Bloom a été développée pour la formalisation à gros grain de cours voire de formation. ``` À 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. Ces annotations s'appuient sur une ontologie, temporairement hébergée dans le fichier de configuration `init-laby/book/_config.yml`. Cette ontologie liste les notions définies dans le cours, avec pour chacun d'entre eux les items suivants : - `verbalization`: comment nous avons choisi de nommer la notion dans le contexte de ce cours; - `en` (optionnel): une traduction en anglais (américain); - `mathhub` (optionnel): un alignement avec l'identifiant de la notion dans l'[ontologie MathHub](https://mathhub.info/dashboard/mathhub); - `wikidata` (optionnel): un alignement avec l'identifiant de la notion dans wikidata - `depends_on` (optionnel): une autre notion qui doit être apprise avant celle-ci. - `group` (optionnel): une autre notion qui définit un groupe dont celle-ci fait partie. Par exemple, la notion «paramètre» fait partie du groupe de la notion «fonction». Cette ontologie est actuellement utilisée pour : - aider les auteurs à standardiser la terminologie - enrichir la définition du terme dans le HTML produit avec la traduction anglaise et d'éventuels liens croisés - annoter le contenu avec des prérequis et objectifs d'apprentissage comme décrit ci-dessus. À terme, elle sera utilisée pour faciliter : - l'assistance automatique à la traduction; - l'enseignement adaptatif; - la visualization des progrès des étudiants par notion plutôt que par activité. ### Citations Lorsque l'on récupère ou s'inspire d'une ressource, on la cite avec le [mécanisme de citation de MyST](https://mystmd.org/guide/citations) avec, autant que possible, une url pointant précisément sur le fragment réutilisé. ```markdown :::{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](https://jupyterbook.org/en/stable/content/content-blocks.html#notes-warnings-and-other-admonitions), [MySTmd](https://mystmd.org/guide/directives#directive-admonition), 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](https://jupyterbook.org/en/stable/content/content-blocks.html#notes-warnings-and-other-admonitions) `hint`, `tip`, `seealso`, etc. Par exemple, l'encart suivant : ```markdown :::{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 : ```markdown :::{admonition} Exemple ... ::: ``` Apartés, rappels, remarques, pour aller plus loin : ```markdown :::{admonition} Aparté : Lorem ipsum :class: hint ::: ``` ```markdown :::{admonition} Les machins en Python :class: hint ... ::: ``` Astuces, indications, ... ```markdown :::{admonition} Astuce :class: tip ... ::: ``` Voir aussi, références, ... ```markdown :::{seealso} Voir aussi ... ::: ``` ```{admonition} Comment choisir la classe? - `hint` pour donner à réfléchir - `tip` pour suggérer des actions - `seealso` pour renvoyer à des information ailleurs ``` Lorsque l'on utilisera MyST ou JupyterBook 2, on pourra utiliser une version plus courte : ```markdown :::{hint} Aparté : Lorem ipsum ... ::: ``` 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. ```markdown :::{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 : ```markdown :::{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 ipsum` où 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 ```markdown (bidule)= :::{admonition} Définition : Bidule Un {definiendum}`bidule` ... ::: ``` Le rôle `definiendum` indique la notion qui est définie, ainsi que le label avec lequel référencer cette notion. Si la notion et le label diffèrent (par exemple pour des questions d'accord), on peut utiliser : ```markdown Les {definiendum}`bidules ` ... ``` 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 `_`. ```{admonition} Motivation --- class: hint --- Cette annotation sémantique des 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 la notion. À terme elle permettra de générer des flashcards pour des révisions, facilitera l'enseignement adaptatif, etc. Voir aussi [Ontologie et annotations sémantique](#ontology). ``` ```{todo} Implanter le rôle `definiendum` sur py-edu-fr. ``` Définitions avec encarts Syntaxe et Sémantique: ```markdown ::::{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](https://mystmd.org/guide/exercises) 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. ```markdown :::{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 fiche (en attendant que ce soit fait automatiquement). ```markdown :::{admonition} Exercice 3 : lorem ipsum ... ::: ``` MyST dans une fiche 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 : ```markdown :::{admonition} Exercice ... ::: ``` puis dans les cellules de texte suivantes: ```markdown :::{admonition} Exercice (suite) ... ::: ``` ```` ```{attention} Une «admonition» sans contenu est un abus de la syntaxe MyST; tous les outils ne la gère pas bien. On essaye d'éviter quand on peut. ```` ## 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](https://gitlab.com/travo-cr/travo-prepare/) qui suit et étends les conventions de [nbgrader](https://nbgrader.readthedocs.io/) (à 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. ```python 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 : ```markdown 1. Décrivez bla bla bla BEGIN SOLUTION bla bla bla END SOLUTION ``` Pour des solutions que l'on souhaite inclure dans la fiche de l'étudiant, on pourra utiliser alternativement un encart «Solution», replié ou pas par défaut : ```markdown :::{admonition} Solution :class: dropdown ... ::: ``` À terme, lorsque JupyterLab-MyST donnera un rendu satisfaisant, on pourra utiliser l'encart standard : ```markdown :::{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](https://gitlab.com/travo-cr/travo-prepare/#documentation) pour les détails. ## Exercices Jupylates Voir la [documentation](https://github.com/nthiery/jupylates/?tab=readme-ov-file#documentation) de Jupylates.