Repository navigation
Expand file tree
/
Copy pathREADME.Rmd
More file actions
91 lines (58 loc) · 3.88 KB
/
Copy pathREADME.Rmd
File metadata and controls
91 lines (58 loc) · 3.88 KB
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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Edit ONLY this file if you need to make a change in README.md. But, after you edit it, you need to run devtools::build_readme() in order to create the new README.md, which is the thing which is actually used. -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/README-",
out.width = "100%"
)
```
# Tutorial Helper Functions
<!-- badges: start -->
[](https://github.com/PPBDS/tutorial.helpers/actions)
<!-- badges: end -->
## About this package
**tutorial.helpers** provides functions to help you write R tutorials, especially if you follow [my advice](https://ppbds.github.io/tutorial.helpers/articles/ai.html) about the best way to do so.
## Installation
To install the package from CRAN:
``` r
install.packages("tutorial.helpers")
```
You can install the development version from [GitHub](https://github.com/) with:
``` r
remotes::install_github("PPBDS/tutorial.helpers")
```
## Useful tools
#### Creating a tutorial
To create a new tutorial, you first need a new directory, located in the `inst/tutorials` directory of your package. Create a `tutorial.Rmd` file within it. The [AI vignette](https://ppbds.github.io/tutorial.helpers/articles/ai.html) provides a highly opinionated framework for teaching students how to use AI to do data science, including the required `info_section` and `download-answers` chunks which every tutorial should contain.
#### Testing
The package includes two important functions: `make_exercise()` and `check_current_tutorial()`. Use `make_exercise()` to add a new exercise to the current tutorial. It will number the exercise, and the code chunk labels, automatically. Use `check_current_tutorial()` to renumber all the exercises and relabel all the code chunks. This is especially useful if you add or delete an exercise in the middle of a section.
There are three exported functions for checking the tutorials in your package. See the [testing vignette](https://ppbds.github.io/tutorial.helpers/articles/testing.html) for details on their use.
#### Tutorials
The package includes the "Getting Started" tutorial, which uses VS Code on GitHub Codespaces. You should require your students to complete it if you are creating your own tutorials with the **tutorial.helpers** package. Have students run:
````
learnr::run_tutorial("getting-started", package = "tutorial.helpers")
````
This will teach them enough about how tutorials work to be able to complete the tutorials you write.
#### Download answers
The most useful tool is the [download answers trick](https://ppbds.github.io/tutorial.helpers/articles/downloads.html). In your tutorial, simply include `library(tutorial.helpers)` in the setup R code chunk and then insert this empty code chunk at the end.
````{verbatim}
```{r download-answers, child = system.file("child_documents/download_answers.Rmd", package = "tutorial.helpers")}
```
````
This will ask the student to provide an estimate of how long the tutorial took to complete. It will then provide the ability to download the student's answers in html format. Students submit these files to their instructors, who can then confirm that the work was completed and look for any patterns in student (mis)understandings.
#### Recommended components
We recommend including this child document at the start of each tutorial:
````{verbatim}
```{r info-section, child = system.file("child_documents/info_section.Rmd", package = "tutorial.helpers")}
```
````
This will insert (optional) questions asking for the student's name, email and id.
We recommend ending the tutorial with the download-answers child document, as discussed above.
````{verbatim}
```{r download-answers, child = system.file("child_documents/download_answers.Rmd", package = "tutorial.helpers")}
```
````