-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathlearnr.qmd
156 lines (103 loc) · 4.29 KB
/
learnr.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
---
title: "Nouveautés {learnr}"
format: html
lang: fr
toc: true
author:
- Pierre Barbillon
- Marie-Pierre Etienne
- Isabelle Sanchez
date: 08/24/2023
---
# Introduction
Nous allons ici présenter les nouveautés du package {learnr} qui permet de créer des tutoriaux interactifs. {learnr} avait déjà été discuté durant la [semaine Finist'R 2020](https://stateofther.github.io/finistR2020/teach_learnr_gradethis.html){.uri}
{learnr} repose sur {shiny}. Le tutoriel est construit à partir d'un fichier Rmarkdown et peut être soit executé en local via le bouton `run app` soit en déployant le fichier sur un serveur Shiny.
Depuis 2020 environ, il est possible d'intégrer un tutoriel {learnr] dans un package, ce qui rend les classiques vignettes interactives. Les nouvelles versions de RStudio ont de plus inclus un bouton `tutorial` disponible dans le panel "Environnement, Git etc...".
L'idée est de partager un tutoriel facilement à une large audience et pour cela il est maintenant possible de les intégrer dans un package. Cela peut être intéressant pour des tutoriaux à destination d'étudiants mais également pour des tutoriaux à intégrer dans les packages que vous développez pour rendre l'initiation aux méthodes développées plus interactives qu'une vignette.
L'avantage technique d'intégrer un tutoriel {learnr} dans un package est qu'il est alors possible, après avoir installé le package, d'exécuter le tutoriel en local sans avoir à le déployer sur un serveur Shiny. C'est donc gratuit et simple d'utilisation.
A noter qu'il n'est pas nécessaire que le package contenant le tutoriel soit déposé sur le CRAN ou autre, qu'il contienne d'autres fichiers que le tutoriel. Tout est donc possible.
Les étapes pour créer un package contenant un tutoriel:
1. Si le package n'est pas déjà créé:
```{r}
#| eval: false
usethis::create_package("<path_to_folder/name_of_package>")
```
1. Pour créer le fichier du tutoriel:
```{r}
#| eval: false
usethis::use_tutorial("<name-of-learnr-file>", "<Title You'd Like the User to See>")
```
1. Puis dans RStudio, cliquer sur "Build \> Install and Restart".
2. Si nécessaire, rajouter le package {gradethis} (noter la fonction de {usethis} spécifique pour les install de package en développement),
```{r}
#| eval: false
usethis::use_dev_package("gradethis")
```
3. Si nécessaire, rajouter les packages présent sur le CRAN toujours avec {usethis}
```{r}
#| eval: false
usethis::use_package("palmerpenguins")
```
4. Si nécessaire, éditer le fichier DESCRIPTION
5. Exécuter `usethis::use_readme_rmd()` pour rajouter un fichier README. puis compiler le tout.
6. Déposer le package sur gitlab ou github puis partager le repository qui peut être installé avec les lignes de code suivantes:
```{r}
#| eval: false
devtools::install_github("<your-repo>/<package-name>")
devtools::install_gitlab("<your-repo>/<package-name>")
```
7. Lorsque le package est installé, aller dans le panel `Tutorial` dans RStudio et c'est parti...
8. Quelques outils utiles.
Il est possible de chaîner des chunks en utilisant la fonctionnalité `exercise.setup` dans les chunks.
Par exemple, nous pouvons effectuer
````markdown
`r ''````{r exo1,exercise=TRUE}
```
````
````markdown
`r ''````{r exo1-solution}
x = 2+1
```
````
````markdown
`r ''````{r exo2,exercise=TRUE,exercise.setup="exo1-solution"}
```
````
````markdown
`r ''````{r exo2-solution,exercise.setup="exo1-solution"}
y = x *3
```
````
````markdown
`r ''````{r exo3,exercise=TRUE,exercise.setup="exo2-solution"}
```
````
etc.
Le package {gradethis} permet de vérifier les solutions proposées à un exercice. Par exemple,
L'exercice consiste à faire 2+3
````markdown
`r ''````{r exo3}
```
````
````markdown
`r ''````{r exo3-solution}
2+3
```
````
on ajoute un chunk pour vérifier que le code est le bon (mais cela demande que la solution proposée contienne le même code que dans la solution)
````markdown
`r ''````{r exo3-code-check}
grade_this_code()
```
````
sinon on peut simplement vérifier la sortie du code proposé par l'utilisateur :
````markdown
`r ''````{r exo3-check}
grade_result(
pass_if(~identical(.result, 5))
)
```
````
# Références
1. https://rstudio.github.io/learnr/
2. https://education.rstudio.com/blog/2020/09/delivering-learnr-tutorials-in-a-package/