Merge branch 'master' into jeff/rs-version

* master: simplify RStudio author. Helps with pkgdown down the road Use CRAN version of sortable with travis (#324) Remove `...` from `correct()` docs (#323) Remove private setting in yaml header. Leave commented example in `hello` tutorial document add private, description, and yaml_front_matter to available_tutorials() output internal -> private update NEWS add descriptions to bundled tutorials; document use
rstudio · Feb 5, 2020 · e14e64f · e14e64f
2 parents cd3c5cf + 4f572e4
commit e14e64f
Show file tree

Hide file tree

Showing 25 changed files with 167 additions and 62 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -22,7 +22,7 @@ jobs:
       if: branch IN (master, travis) AND repo = rstudio/learnr AND type = push
       r: release
       warnings_are_errors: false
-      r_github_packages:
-        - rstudio/sortable
+      r_packages:
+        - sortable
       script:
       - Rscript tools/deploy_tutorials_on_travis.R
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -7,7 +7,7 @@ Authors@R: c(
         comment = c(ORCID = "0000-0001-9986-114X")),
   person("JJ", "Allaire", role = "aut", email = "jj@rstudio.com"),
   person("Barbara", "Borges", role = "aut", email = "barbara@rstudio.com"),
-  person(family = "RStudio, Inc.", role = "cph"),
+  person("RStudio", role = c("cph", "fnd")),
   person(family = "Ajax.org B.V.", role=c("ctb", "cph"), comment= "Ace library"),
   person("Zeno", "Rocha", role = c("ctb", "cph"), comment = "clipboard.js library"),
   person("Nick", "Payne", role = c("ctb", "cph"), comment = "Bootbox library"),
@@ -42,7 +42,7 @@ Remotes:
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 6.1.1
+RoxygenNote: 7.0.2
 Suggests:
     testthat (>= 2.1.0),
     callr,

diff --git a/NEWS.md b/NEWS.md
@@ -3,14 +3,16 @@ learnr 0.10.0.9000 (unreleased)
 
 ## New features
 
-
 ## Minor new features and improvements
 
+* `learnr`'s built-in tutorials now come with a description as part of the YAML header, with the intention of this being used in front-end software that catalogues available `learnr` tutorials on the system. ([#312](https://github.com/rstudio/learnr/issues/312))
 
 ## Bug fixes
 
 * Fixed a bug where broken exercise code created non-"length-one character vector". ([#311](https://github.com/rstudio/learnr/pull/311))
 
+* Fixed extra parameter documentation bug. ([#323](https://github.com/rstudio/learnr/pull/323))
+
 
 learnr 0.10.0
 ===========

diff --git a/R/available_tutorials.R b/R/available_tutorials.R
@@ -33,7 +33,14 @@ available_tutorials <- function(package = NULL) {
 }
 
 
-#' @return will return a list of `error` and `tutorials` which is a \code{data.frame} containing "package", "name", and "title".
+#' @return will return a list of `error` and `tutorials`.
+#'   `tutorials` is a \code{data.frame} containing
+#'    "package": name of package; string
+#'    "name": Tutorial directory. (can be passed in as `run_tutorial(NAME, PKG)`; string
+#'    "title": Tutorial title from yaml header; [NA]
+#'    "description": Tutorial description from yaml header; [NA]
+#'    "private": Boolean describing if tutorial should be indexed / displayed; [FALSE]
+#'    "yaml_front_matter": list column of all yaml header info; [list()]
 #' @noRd
 available_tutorials_for_package <- function(package) {
 
@@ -68,12 +75,19 @@ available_tutorials_for_package <- function(package) {
       return(NULL)
     }
     if (dir_rmd_files_length > 1) {
-      warning("Found multiple .Rmd files in \"", package, "\"'s \"", tut_dir, "\" folder.  Using: ", dir_rmd_files[1])
+      warning(
+        "Found multiple .Rmd files in \"", package, "\"'s \"", tut_dir, "\" folder.",
+        "  Using: ", dir_rmd_files[1]
+      )
     }
+    yaml_front_matter <- rmarkdown::yaml_front_matter(dir_rmd_files[1])
     data.frame(
       package = package,
       name = basename(tut_dir),
-      title = rmarkdown::yaml_front_matter(dir_rmd_files[1])$title %||% NA,
+      title = yaml_front_matter$title %||% NA,
+      description = yaml_front_matter$description %||% NA,
+      private = yaml_front_matter$private %||% FALSE,
+      yaml_front_matter = I(list(yaml_front_matter)),
       stringsAsFactors = FALSE,
       row.names = FALSE
     )
@@ -90,6 +104,7 @@ available_tutorials_for_package <- function(package) {
 
   tutorials <- do.call(rbind, rmd_info)
   class(tutorials) <- c("learnr_available_tutorials", class(tutorials))
+  rownames(tutorials) <- NULL
 
   list(
     tutorials = tutorials,
@@ -152,17 +167,28 @@ format.learnr_available_tutorials <- function(x, ...) {
   tutorials <- x
   ret <- "Available tutorials:"
 
+  tutorials <- tutorials[!tutorials$private, , drop = FALSE]
+
   for (pkg in unique(tutorials$package)) {
-    tutorials_sub <- tutorials[tutorials$package == pkg, ]
+    tutorials_sub <- tutorials[tutorials$package == pkg, , drop = FALSE]
 
     tutorial_names <- format(tutorials_sub$name)
-    txts <- mapply(tutorial_names, tutorials_sub$title, SIMPLIFY = FALSE, FUN = function(name, title) {
-      txt <- paste0("  - ", name)
-      if (!is.na(title)) {
-        txt <- paste0(txt, " : \"", title, "\"")
+    txts <- mapply(
+      tutorial_names,
+      tutorials_sub$title,
+      SIMPLIFY = FALSE,
+      FUN = function(name, title) {
+        txt <- paste0("  - ", name)
+        if (!is.na(title)) {
+          txt <- paste0(txt, " : \"", title, "\"")
+        }
+        width <- getOption("width", 80)
+        if (nchar(txt) > width) {
+          txt <- paste0(substr(txt, 1, width - 3), "...")
+        }
+        txt
       }
-      txt
-    })
+    )
 
     ret <- paste0(
       ret, "\n",

diff --git a/R/question_methods.R b/R/question_methods.R
@@ -109,7 +109,6 @@ question_is_correct.default <- function(question, value, ...) {
 #' Helper method to return
 #' @param correct boolean that determines if a question answer is correct
 #' @param messages a vector of messages to be displayed.  The type of message will be determined by the `correct` value.
-#' @param ... possible future parameter expansion
 #' @rdname mark_as_correct_incorrect
 #' @export
 #' @examples

diff --git a/docs/index.Rmd b/docs/index.Rmd
@@ -61,9 +61,10 @@ This is what the running tutorial document looks like after the user has entered
 
 A tutorial is just a directory that contains a standard R Markdown document with three additional attributes:
 
-1. Loads the **learnr** package.
-2. Includes one or more interactive components (exercises, quiz questions, etc.).
-3. Uses the `runtime: shiny_prerendered` directive in the YAML header.
+1. Loads the **learnr** package,
+2. Includes one or more interactive components (exercises, quiz questions, etc.),
+3. Uses the `runtime: shiny_prerendered` directive in the YAML header,
+4. Provides a short description in the top-level `description:` field of the YAML header.
 
 The `runtime: shiny_prerendered` element included in the YAML hints at the underlying implementation of tutorials: they are simply Shiny applications which use an R Markdown document as their user-interface rather than the traditional `ui.R` file.
 

diff --git a/docs/snippets/tutorialyaml-progressive.md b/docs/snippets/tutorialyaml-progressive.md
@@ -4,4 +4,4 @@ output:
   learnr::tutorial:
     progressive: true
 runtime: shiny_prerendered
----
+---
diff --git a/docs/snippets/tutorialyaml.md b/docs/snippets/tutorialyaml.md
@@ -2,4 +2,5 @@
 title: "Hello, Tutorial!"
 output: learnr::tutorial
 runtime: shiny_prerendered
----
+description: "Welcome to learnr tutorials!"
+---
diff --git a/inst/tutorials/ex-data-basics/ex-data-basics.Rmd b/inst/tutorials/ex-data-basics/ex-data-basics.Rmd
@@ -6,6 +6,9 @@ output:
     allow_skip: true
     df_print: default
 runtime: shiny_prerendered
+description: >
+  Learn about the base data types in R. Explore R's data frames, and learn how
+  to interact with data frames and their columns.
 ---
 
 ```{r setup, include=FALSE}

diff --git a/inst/tutorials/ex-data-filter/ex-data-filter.Rmd b/inst/tutorials/ex-data-filter/ex-data-filter.Rmd
@@ -5,6 +5,10 @@ output:
     progressive: true
     allow_skip: true
 runtime: shiny_prerendered
+description: >
+  Learn how to filter observations in a data frame. Use `filter()` to extract
+  observations from a data frame, and use `&`, `|`, and `!` to write logical
+  tests.
 ---
 
 ```{r setup, include=FALSE}

diff --git a/inst/tutorials/ex-data-mutate/ex-data-mutate.Rmd b/inst/tutorials/ex-data-mutate/ex-data-mutate.Rmd
@@ -5,6 +5,8 @@ output:
     progressive: true
     allow_skip: true
 runtime: shiny_prerendered
+description: >
+  Learn how to select, create, and mutate variables in a data frame.
 ---
 
 ```{r setup, include=FALSE}

diff --git a/inst/tutorials/ex-data-summarise/ex-data-manip-summarise.Rmd b/inst/tutorials/ex-data-summarise/ex-data-manip-summarise.Rmd
@@ -5,6 +5,11 @@ output:
     progressive: true
     allow_skip: true
 runtime: shiny_prerendered
+description: >
+  Learn how to summarize the columns available in an R data frame with
+  `summarise()`. You will also learn how to chain operations together with the
+  magrittr pipe operator `%>%`, and how to compute grouped summaries using
+  `group_by()` together with `summarise()`.
 ---
 
 ```{r setup, include=FALSE}

diff --git a/inst/tutorials/ex-setup-r/ex-setup-r.Rmd b/inst/tutorials/ex-setup-r/ex-setup-r.Rmd
@@ -5,6 +5,9 @@ output:
     progressive: true
     allow_skip: true
 runtime: shiny_prerendered
+description: >
+  Learn how to set up R and RStudio on your machine. We will also demonstrate
+  how to install R packages from CRAN, and install the tidyverse package.
 ---
 
 ```{r setup, include=FALSE}

diff --git a/inst/tutorials/hello/hello.Rmd b/inst/tutorials/hello/hello.Rmd
@@ -4,15 +4,18 @@ author: "J.J. Allaire"
 date: "March 1st, 2017"
 output: learnr::tutorial
 runtime: shiny_prerendered
+# Do not index/display tutorial by setting `private: true`
+# private: true
+description: >
+  This is a demo tutorial.
 ---
 
 ```{r setup, include=FALSE}
 library(learnr)
 ```
-    
+
 The following code computes the answer to 1+1. Change it so it computes 2 + 2:
-    
+
 ```{r addition, exercise=TRUE}
 1 + 1
 ```
-
diff --git a/inst/tutorials/quiz_question/quiz_question.Rmd b/inst/tutorials/quiz_question/quiz_question.Rmd
@@ -8,6 +8,9 @@ tutorial:
   # id: "com.example.tutorials.my-first-tutorial"
   version: 2.18
   # user_id: "barret"
+description: >
+  This tutorial demonstrates how multiple-choice questions can be created within
+  a learnr tutorial.
 ---
 
 ```{r setup, include=FALSE}

diff --git a/inst/tutorials/slidy/slidy.Rmd b/inst/tutorials/slidy/slidy.Rmd
@@ -2,6 +2,9 @@
 output: slidy_presentation
 runtime: shiny_prerendered
 title: "Slidly demo"
+description: >
+  This tutorial demonstrates how one can use dygraphs (with the dygraph package)
+  as part of a learnr tutorial.
 ---
 
 ```{r setup, include=FALSE}

diff --git a/man/format_quiz.Rd b/man/format_quiz.Rd
diff --git a/man/mark_as_correct_incorrect.Rd b/man/mark_as_correct_incorrect.Rd
diff --git a/man/question_checkbox.Rd b/man/question_checkbox.Rd
diff --git a/man/question_methods.Rd b/man/question_methods.Rd
diff --git a/man/question_radio.Rd b/man/question_radio.Rd
diff --git a/man/question_text.Rd b/man/question_text.Rd
diff --git a/man/quiz.Rd b/man/quiz.Rd