In muschellij2/didactr: Tools for Creating Automated Courses

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(didactr)
auth_file = "../tests/testthat/googlesheets_token.rds"
if (file.exists(auth_file)) {
  didactr_auth(token_file = auth_file)
} else {
  x = didactr_auth()
}
stopifnot(check_didactr_auth())

Quick rundown

Creating a Course

1. Open RStudio.
2. Install didactr

devtools::install_github("muschellij2/didactr")

1. Load didactr.

library(didactr)

1. Create a course. Change course_name to your course name, and change root_path to where you want the course created on disk:

didactr::create_course(
  course_name = "My Course Name", 
  root_path = "/path/to/course/on/disk", 
  open = TRUE)

This should open up a new RStudio session. Make sure you run:

library(didactr)

in your new session.

Creating a Lesson

1. Go to your Google Slide deck and copy the URL from the slide deck

knitr::include_graphics("../man/figures/copy_url.png")

1. Create a lesson. For your lesson, change How to Do Things to something more appropriate and run in your new session, pasting in the slide URL:

out = didactr::create_lesson(
  lesson_name = "How to Do Things",
  course_dir = ".",
  slide_id = "URL FOR GOOGLE SLIDE DECK",
  make_slide_deck = TRUE,
  open = TRUE)

Full Documentation

You should have the most up to date RStudio downloaded and installed.

If you don't have didactr installed

If you do not have didactr installed, you can run the following command:

devtools::install_github("muschellij2/didactr")

Setting up a Temporary Course

Let's load in the didactr library:

library(didactr)

In this tutorial we will work in temporary directories in R. In your case, you want to change root_path to a folder on your computer where your class will live. The class folder will be in root_path/course_name. Run the code below, changing root_path to a path on your computer where you want the course folder.

root_path = tempfile()

root_path = "/the/path/to/your/course"

(In this example, we are setting it to a temporary directory so it deletes itself once we're done.)

Here we will call our course name test. For course names, these should not have any spaces; all slide decks will have the course_name prepended on them (for example test_00_first_lecture). The create_course function will create the course. Run the code below, changing test to the name of the course that you want. If do not want R to open up the R project (in the directory of the course), set open = FALSE in the code below:

course_name = "test"
sc = didactr::create_course(course_name, root_path, open = TRUE)

course_name = "test"
sc = didactr::create_course(course_name, root_path, open = FALSE)

Make sure you run:

library(didactr)

in your new session.

We see the paths that have been created for the project. You may ask yourself "Why were all these folders created?"; we discuss below the folder structure necessary for Leanpub courses.

For the rest of the code below, you need to go to your course directory. You can do this by opening (on your machine) your course_name.Rproj file in your course directory (in our example test.Rproj).

If you have a PowerPoint or PDF

This workflow uses Google Slides to create your video and your document. We highly recommend this process. If you have a local presentation and you want to use that, go to https://drive.google.com (by clicking on the link). Once on Google Drive, click the New button:

knitr::include_graphics("../man/figures/New.png")

After clicking that, select "File Upload":

knitr::include_graphics("../man/figures/Upload.png")

Then upload your deck.

Starting with a Google Slide Deck

x = "https://docs.google.com/presentation/d/1Tg-GTGnUPduOtZKYuMoelqUNZnUp3vvg_7TtpUPL7e8/edit#slide=id.g154aa4fae2_0_58"

If you start with a Google Slide deck, you need the Slide ID. Please go to the slide deck on Google Slides, and then copy the URL from the browser address bar:

knitr::include_graphics("../man/figures/copy_url.png")

For example, let's say we copied https://docs.google.com/presentation/d/1Tg-GTGnUPduOtZKYuMoelqUNZnUp3vvg_7TtpUPL7e8/edit#slide=id.g154aa4fae2_0_58 from our address bar. The ID is r ariExtra::get_slide_id(x), and didactr provides the helper function ariExtra::get_slide_id that takes in this URL and provides the slide ID. You can either copy just the slide ID or run ariExtra::get_slide_id on your URL as the example below demonstrates.

my_slide_url = "https://docs.google.com/presentation/d/1Tg-GTGnUPduOtZKYuMoelqUNZnUp3vvg_7TtpUPL7e8/edit#slide=id.g154aa4fae2_0_58"
slide_id = ariExtra::get_slide_id(my_slide_url)
slide_id
# copy this to slide_id
# for example:
# slide_id = "1Tg-GTGnUPduOtZKYuMoelqUNZnUp3vvg_7TtpUPL7e8"

If you don't have start with a slide deck, you can simply run the create_lesson command and it will create a Google Slide deck copy from one we provide. If you do not have a slide deck, you can run:

slide_id = NULL

Otherwise, you should run the command, where you removed the example URL and put in your own URL:

slide_id = ariExtra::get_slide_id("URL FOR GOOGLE SLIDE DECK")

Before we actually make the lesson, please read this note on authorization.

Creating the Lesson

The create_lesson function will pop up windows for you to the authorize didactr to work with your Google Drive/Google Slides.

Accept the permissions to use didactr. It will ask you once for Google, once for YouTube.

NOTE: this function will make your slide deck public. This is so that Leanpub can download your slides into your manuscript.

Now, let's create our lesson. For your lesson, change How to Do Things to something more appropriate and run:

sc = check_structure(course_dir = ".", create_directories = FALSE)
stopifnot(dir.exists(sc$man_path))
out = didactr::create_lesson(
  lesson_name = "How to Do Things",
  course_dir = sc$course_dir,
  make_slide_deck = TRUE,
  slide_id = slide_id,
  open = TRUE)
out

out = didactr::create_lesson(
  lesson_name = "How to Do Things",
  course_dir = sc$course_dir,
  make_slide_deck = TRUE,
  slide_id = slide_id,
  open = FALSE)
out

Viewing the Lesson

Run leanpub_render to view the output of your lesson:

didactr::leanpub_render(out$md_file)

If you are including png or other files with links and not included in the manuscript/resources/images folder in your course, then you must specify the format before the Markdown. For example if you want to include a PNG from Google Slides, we can use the following lines:

{format: png}
![](https://docs.google.com/presentation/d/143gvqcynq_bl7iVd2G9yjumwJJkAy0S6CyNCsrJ2LgE/export/png?id=143gvqcynq_bl7iVd2G9yjumwJJkAy0S6CyNCsrJ2LgE&pageid=p)

Courses using didactr

In didactr, we not only create a Leanpub course, which has text and quizzes, we also create automated videos. You do not have to create these videos to use didactr and can use didactr only to create Leanpub courses on their own without videos.

Video Generation

If you want to generate videos for a lesson, you need FFmpeg. You need to make sure you have FFmpeg version 3.2.4 or higher installed on your system. If you would like to try to install ffmpeg automatically, please try:

didactr::install_ffmpeg()

If a path comes up, you have ffmpeg installed! If not you can go to https://ffmpeg.org/ for instructions on installation. Some recommendations are:

• OSX: using Brew brew install ffmpeg. See the Brew page for brew installation.
• Linux variants: sudo apt-get install -y ffmpeg
• Windows: using Chocolatey: choco install ffmpeg

Creating a video from a Google Slides Deck

If you have a Google Slides presentation with the text to be spoken over the slides in the speaker notes section of the presentation, you can run:

res = gs_ari(id = "URL FOR GOOGLE SLIDE DECK")

If you choose to create videos with didactr we have additional things we need over and above what Leanpub need:

1. A scripts folder which contains .md files that correspond to the spoken words to be said over the slides. These are plain text (not markdown) and "special" words need to be phonetically spelled, such as R Studio. Each newline separates slides, so there needs to be the same number of non-empty lines as the number of slides in the slide deck.
2. A manuscript/resources/videos folder which contains the synthesized videos from the Google Slide deck and the script. The audio is generated by Amazon Polly.
3. If you want to create videos with automated voices, you need to create an Amazon account. See https://github.com/cloudyr/aws.signature for more information.

Specification for a Script

A script file must have as many non-empty lines as there are slides. If you don't want any text read over the slide, simply add a simple semicolon ";" or comman ",".

Checking a Course

The check_course function is the main function for determining if the structure of the course is setup correctly. This checks a lot of different folders and such. If you've created the course using create_course, these should likely have been created already. Videos and other resources _

result = didactr::check_course(course_dir = sc$course_dir, check_youtube_links = FALSE)
result$course_summary

If there are multiple warnings, this may be due to the YouTube links not included, the Google Slide ID not included, or the number of paragraphs in the scripts not matching up with the number of slides.

Changes to Manuscript files

Now that you have a lesson created, you likely want to change the content and the slides over time. Let's say you want to include a slide, you can use the gs_slide_df function. The output is a tibble with a lot of elements. You can extract objectId to grab the "page" identifier, which is unique to that specific slide in the deck. Note, the ID and slide ID combination together make it unique over all of Google, not simply the page ID. For example, most first slides have the ID p.

slide_df = didactr::gs_slide_df(id = result$course_summary$id[1])
slide_df$objectId

Code inside a text box

If you have code in a Google Slide deck and want to extract it, you must mark in the Google Slide Deck. You can either:

1. You can add #rstats to the text box anywhere.
2. Right click the text box and add the title #rstats to the Alt-text. Right click the text box → Alt text... → Title #rstats.

For example, we have a slide deck with some code and here is the output:

out_rmd = didactr::create_lesson(
  lesson_name = "An example with some code",
  course_dir = sc$course_dir,
  slide_id = "1Tg-GTGnUPduOtZKYuMoelqUNZnUp3vvg_7TtpUPL7e8",
  extract_code = TRUE,
  rmd = TRUE,
  open = FALSE)
x = readLines(out_rmd$md_file)
ind = grep("```\\{r [^setup]", x)[1]
cat(x[(ind - 5):(ind + 14)], sep = "\n")

Keeping Repositories Light

As videos can be very large, we likely don't want to upload them to spaces like GitHub. As such, by default, the videos directory is excluded from git:

readLines(file.path(sc$course_dir, ".gitignore"))

Now we will create a lesson in that course. There are a few ways to do this. If you have Markdown/md files already and have a Book.txt, which is required for Leanpub, then you want to look at the create_lessons_from_book function. As we are starting from scratch, we will assume you have at most a Google Slides deck, but this is not required.

Leanpub courses

If you've never created a Leanpub, the structure is that the top-level folder is a course. The course has the following components:

1. A manuscript folder with a Markua/md file for each lesson. Markua is a subset of Markdown, but has additional elements for quizzes and other teaching.
2. A Book.txt in the manuscript folder. This Book.txt is a simple text file that determines the order of the lessons, with one line for each .md file. The suffix needs to be included and the file names need to match exactly.
3. A manuscript/resources folder, which contains an images sub-folder with png/images for each lesson. We will not use these in this workflow as all images are directly encoded from a Google Slide deck.

Making Local Data

If you want to take the Google Slides and download them into individual PNGs so you can view them, the gs_convert takes in an ID and then converts the images to PNGs. This requires the convert function and ImageMagick being installed. If you use the gs_convert(..., use_gs_ids = TRUE), the files will be named using the Google Slide page ID, which can allow you to "link" the image to the ID, so you can use

{format: png}
![](https://docs.google.com/presentation/d/SLIDE_ID/export/png?id=SLIDE_ID&pageid=PAGE_ID)

in your manuscript files, shere SLIDE_ID is the Google Slide deck ID and PAGE_ID is the page ID given by the filename of the png when use_gs_ids = TRUE.

Troubleshooting

If this errors, that is due to the fact that you are not in your course directory when running it. You must either change the directory to the course directory (using setwd) or open your course folder and open the file that has the extension .Rproj to open a new R session with the right directory set and then run the above commands.

Here we break down the arguments we specified. Whenever create_lesson, you must supply a lesson_name (in our case "How to Do Things"). This can have spaces if you want and will be the title of the lesson. We will pass the course directory in here from our sc object, otherwise it assumes we are creating this in the current working directory. The slide_id again is the slide identifier for a Google Slide deck. The ID can be extracted from the URL manually or running ariExtra::get_slide_id on the URL. If you do not specify a slide ID, the make_slide_deck argument determines if you would like to create a slide deck. If TRUE, it copies a template; if FALSE it does not make a slide deck. NB: if you're creating a slide deck, we are copying over a slide deck from a different Google Drive and may take a few seconds due to the Google Drive API.

The md_file argument allows you to override the standard naming convention we recommend, the rmd argument says whether you'd like to use an Rmarkdown vs. Markdown document. The argument open determines if you'd like to edit the document and script after creating it.

We see the output is the Markdown file, slide ID for the deck, and the output script file (to be spoken over the slides). Here is the output of the MD file:

readLines(out$md_file)

Notably, we see that any area of "Notes" in the Google Slide deck is copied to the manuscript. This is also done for the script:

readLines(out$script_file)

Pandoc

If you have pandoc installed and want to make sure that things should render, run:

rmarkdown:::pandoc_available("1.20")

and make sure this is TRUE.

muschellij2/didactr documentation built on March 17, 2021, 12:45 p.m.