Fonctionnalités de Capytale⚓︎

Voici deux outils qui peuvent rendre des services appréciables :

Les admonitions dans un notebook et
les modules personnels en python.

Les admonitions⚓︎

Fonction⚓︎

Selon le centre national de ressource textuelles et lexicales, une admonition est l'action de donner un avertissement.

Dans les cellules en markdown d'un notebook, les admonitions

servent à mettre en valeur une partie du texte,
en créant facilement des cadres selon un format prédéfini.

Voici un exemple de cadre coloré qui s'obtient très simplement.
L'icône a été automatiquement associée au titre en utilisant un format prédéfini.

Emploi⚓︎

Pour obtenir l'admonition ci-dessus dans un notebook, il suffit d'écrire dans une cellule markdown, le code suivant :
Markdown
```
!!! danger Nouveau
**Deux** types d'admonitions sont désormais supportés.
!!!
```
puis de demander le rendu de cette cellule.

Mode d'emploi

Dans une cellule markdown en mode édition, un cadre est
- initié par la saisie en début de ligne de !!! suivi d'une espace et d'un type de format et
- il est clos par la même séquence de caractères !!!, seule sur une ligne.
On peut donner un titre au cadre en ajoutant après le nom du format, une espace puis le texte souhaité.
Dans l'exemple ci-dessus,
- le titre Nouveau a été automatiquement formaté en gras,
- le formatage utilisé s'appelle danger, d'où le ton rouge et l'éclair symbolisé.
Voici la liste des icônes et des noms, de tous les formats existants :

`success`	`tip`	`danger`	`info`	`question`	`bug`
`note`	`warning`	`example`	`abstract`	`failure`	`quote`

Circonstance⚓︎

Les admonitions sont utilisables dans toute cellule markdown de tout notebook.

Un exemple classique d'utilisation consiste à donner un " style " à ses notebooks en utilisant toujours la même admonition pour matérialiser :

les définitions que les utilisateurs doivent lire,
les questions qui demandent un travail,
les points de vigilance…

Déplier - replier⚓︎

Il est également très simple de rendre une admonition interactive.

Cliquez ici pour savoir comment

On remplace les !!! par des ??? et on obtient ce type d'affichage.
Cliquez à nouveau sur le titre de ce texte pour replier ce cadre.

Ces cadres dépliables sont pratiques, entre autres pour apporter une aide, dont l'élève décide du moment où il l'utilise.

Voici une admonition dépliable :

Aide

Essayez dans le notebook fonctionnel ci-dessous :

La première cellule contient 2 admonitions :
- Essayez de deviner le code puis
- vérifiez en éditant cette cellule.
Créez quelques admonitions au-dessous.

⚓︎

La liste des noms des différentes admonitions est rappelée.
Testez vous-même.

Vous pouvez l'explorer, modifier les cellules pour voir le comportement des admonitions au travail.

Un module python personnel⚓︎

Ce qui suit fonctionne dans Capytale avec toute activité python, aussi bien dans un notebook, que dans une console.

Vocabulaire⚓︎

Comme souvent, il est bon de définir ce que nous allons manipuler :

Un module python est un fichier .py pouvant contenir des instructions, des définitions de fonction ou de variable ou de classe.
Une bibliothèque python est un ensemble de module.
Une librairie est une mauvaise traduction du mot anglais Library qui signifie bibliothèque.

Intérêt⚓︎

Il peut arriver que vous souhaitiez fournir une fonction python complique()¹ à vos élèves.
- Parce que vous ne voulez pas les effrayer avec son code,
- parce que cette fonction a déjà été fabriquée précédemment et qu'il n'y a pas besoin de retravailler son code,
- parce que vous ne souhaitez pas qu'ils aient accès à son code,
- ou pour toute autre raison.
Il suffit de placer cette fonction dans un fichier fourni.py¹ que vous joignez à votre activité.
Vous pouvez alors importer cette fonction dans la mémoire de python lorsque vous le souhaitez.

Cela fonctionne de la même façon pour une variable, une classe…

Joindre le fichier dans Capytale⚓︎

Au moment de la création de l'activité, ou plus tard, en éditant ses Paramètres,
on joint le fichier à l'activité, comme illustré ci-dessous.

Utiliser⚓︎

Lorsque l'élève aura besoin d'utiliser cette fonction, son appel dépendra de la façon dont l'importation a été faite :

On importe uniquement la fonction depuis le module. On importe le module fourni dans son ensemble.

Python

⁝
from fourni import complique 
⁝
# On appelle la fonction comme si on venait de la définir
complique(10) 
⁝

Charge à vous de ne pas remplacer une fonction de même nom, existante ou à venir.

Python

⁝
import fourni  
⁝
# On appelle la fonction complique depuis le module chargé en mémoire avec
fourni.complique(10)
⁝

Le préfixe fourni. indique la provenance de la fonction importée qui est alors différenciée d'une fonction complique qui existerait préalablement ou que l'on définira plus tard.

Invisible est différent de caché

Les élèves ne voient pas le code de complique(), mais pour autant, il ne faut pas croire qu'il leur est inaccessible.
Ils ont accès aux fichiers joints à une activité,
- via l'icône 📎 d'un notebook, puis en suivant le menu Attachés à l'activité.
- ou directement dans l'interface d'une console python.

Si votre intention était de cacher le code, voici la solution :

En commençant son nom par un tiret bas _, le fichier joint sera caché aux élèves. Dans notre exemple, on aurait appelé le module _fourni.py.
Tout ce qui a été dit précédemment continue de fonctionner, mais côté élève, le fichier n'apparaît plus attaché au notebook.

Dans ce cas, n'oubliez pas le tiret bas lors de l'importation ou d'un appel avec le préfixe.

Accès au focus sur une activité

Les noms sont libres tant qu'ils ne téléscopent pas les mots-clés réservés par python.
complique() et fourni.py seront utilisés dans le reste de l'article. ↩↩