v0.11.0 (#735)

Co-authored-by: Alex Rossell Hayes <[email protected]>

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: learnr
 Title: Interactive Tutorials for R
-Version: 0.10.7.9000
+Version: 0.11.0
 Authors@R: c(
     person("Garrick", "Aden-Buie", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0002-7111-0077")),

NEWS.md

@@ -1,4 +1,4 @@
-# learnr (development version)
+# learnr 0.11.0
 
 ## Authoring
 
@@ -48,7 +48,7 @@
 
 -   The `exercise.cap` exercise/chunk option now accepts HTML input. If no `exercise.cap` is provided, the `exercise.cap` will default to the combination of the exercise engine and `" code"` (#397, #429).
 
--   Improved support for SQL exercises makes it possible to check student submissions for SQL exercises (#668).
+-   Improved support for SQL exercises makes it possible to check student submissions for SQL exercises. See `run_tutorial("sql-exericse", "learnr")` or the [online SQL exercise demo](https://learnr-examples.shinyapps.io/sql-exercise) for an example tutorial with graded SQL exercises (#668).
 
 -   Exercise editors now use syntax highlighting and basic autocompletion for exercises in languages other than R with syntax highlighting support for JavaScript, Julia, Python and SQL (#693).
 
@@ -165,7 +165,7 @@
     -   `run_tutorial()` now renders tutorials in a temp directory if the R user does not have write permissions (#347).
 
 -   Many of the HTML dependencies used by learnr have been updated to more recent versions (#655). learnr now uses:
-    -   [Ace](https://ace.c9.io/) version [1.4.14](https://github.com/ajaxorg/ace/blob/HEAD/ChangeLog.txt)
+    -   [Ace](https://ace.c9.io/) version [1.10.1](https://github.com/ajaxorg/ace/blob/ff3dd698/CHANGELOG.md)
     -   [clipboard.js](https://clipboardjs.com/) version [2.0.10](https://github.com/zenorocha/clipboard.js/releases)
     -   [Bootbox](http://bootboxjs.com/) version [5.5.2](https://github.com/makeusabrew/bootbox/blob/master/CHANGELOG.md)
     -   [i18next](https://www.i18next.com/) version [21.6.10](https://github.com/i18next/i18next/blob/master/CHANGELOG.md)
@@ -182,11 +182,11 @@
 
 -   Support the updated Bootstrap 4+ popover dispose method name, previously destroy (#560).
 
--   Forked evaluator (used by default on Linux and [shinyapps.io](https://shinyapps.io)) now only collects the exercise evaluation result once, avoiding a "cannot wait for child" warning (thanks @tombeesley #449, #631).
+-   Forked evaluator (used by default on Linux and [shinyapps.io](https://www.shinyapps.io/)) now only collects the exercise evaluation result once, avoiding a "cannot wait for child" warning (thanks @tombeesley #449, #631).
 
 -   `learnr::tutorial()` now allows authors to adjust the value of `lib_dir` (#648).
 
--   learnr now uses and suggests [shinytest2](https://rstudio.github.io/shinytest2) for automated testing of tutorials in the browser. If you were previously using [shinytest](https://rstudio.github.io/shinytest) to test your tutorials, you may find the [Migrating from shinytest](https://rstudio.github.io/shinytest2/articles/z-migration.html) article to be helpful (#694).
+-   learnr now uses and suggests [shinytest2](https://rstudio.github.io/shinytest2/) for automated testing of tutorials in the browser. If you were previously using [shinytest](https://rstudio.github.io/shinytest/) to test your tutorials, you may find the [Migrating from shinytest](https://rstudio.github.io/shinytest2//articles/z-migration.html) article to be helpful (#694).
 
 # learnr 0.10.1
 
@@ -250,7 +250,7 @@
 
 -   Added a fail-safe to try-catch bad student code that would crash the tutorial (@adamblake #229).
 
--   Replaced references to `checkthat` and `grader` in docs with [gradethis](https://github.com/rstudio-education/gradethis) (#269)
+-   Replaced references to `checkthat` and `grader` in docs with [gradethis](https://github.com/rstudio/gradethis) (#269)
 
 -   Removed a warning created by pandoc when evaluating exercises where pandoc was wanting a title or pagetitle. #303
 

R/ace.R

@@ -1,3 +1,3 @@
 # This file was autogenerated by 'tools/update-ace.R'
-ACE_VERSION <- "1.4.14"
-ACE_THEMES <- c("ambiance", "chaos", "chrome", "clouds_midnight", "clouds", "cobalt", "crimson_editor", "dawn", "dracula", "dreamweaver", "eclipse", "github", "gob", "gruvbox", "idle_fingers", "iplastic", "katzenmilch", "kr_theme", "kuroir", "merbivore_soft", "merbivore", "mono_industrial", "monokai", "nord_dark", "one_dark", "pastel_on_dark", "solarized_dark", "solarized_light", "sqlserver", "terminal", "textmate", "tomorrow_night_blue", "tomorrow_night_bright", "tomorrow_night_eighties", "tomorrow_night", "tomorrow", "twilight", "vibrant_ink", "xcode")
+ACE_VERSION <- "1.10.1"
+ACE_THEMES <- c("ambiance", "chaos", "chrome", "cloud9_day", "cloud9_night_low_color", "cloud9_night", "clouds_midnight", "clouds", "cobalt", "crimson_editor", "dawn", "dracula", "dreamweaver", "eclipse", "github", "gob", "gruvbox_dark_hard", "gruvbox_light_hard", "gruvbox", "idle_fingers", "iplastic", "katzenmilch", "kr_theme", "kuroir", "merbivore_soft", "merbivore", "mono_industrial", "monokai", "nord_dark", "one_dark", "pastel_on_dark", "solarized_dark", "solarized_light", "sqlserver", "terminal", "textmate", "tomorrow_night_blue", "tomorrow_night_bright", "tomorrow_night_eighties", "tomorrow_night", "tomorrow", "twilight", "vibrant_ink", "xcode")

R/debug_exercise_checker.R

@@ -19,6 +19,8 @@
 #' @param engine The engine of the exercise chunk
 #' @param ... Not used (future compatibility)
 #'
+#' @return Feedback for use in exercise debugging.
+#'
 #' @keywords internal
 debug_exercise_checker <- function(
     label,

R/evaluators.R

@@ -158,16 +158,21 @@ forked_evaluator <- setup_forked_evaluator_factory(max_forked_procs = Inf)
 
 #' External execution evaluator
 #'
-#' [Lifecycle: experimental](https://www.tidyverse.org/lifecycle/#experimental)
+#' [Lifecycle: experimental](https://lifecycle.r-lib.org/articles/stages.html)
+#'
 #' @param endpoint The HTTP(S) endpoint to POST the exercises to
 #' @param max_curl_conns The maximum number of simultaneous HTTP requests to the
 #'   endpoint.
+#'
+#' @return A function that takes an expression (`expr`), `timelimit`, `exercise`
+#'   and `session`.
+#'
 #' @import curl
 #' @export
 external_evaluator <- function(
   endpoint = getOption("tutorial.external.host", Sys.getenv("TUTORIAL_EXTERNAL_EVALUATOR_HOST", NA)),
-  max_curl_conns = 50){
-
+  max_curl_conns = 50
+){
   internal_external_evaluator(endpoint, max_curl_conns)
 }
 

R/events.R

@@ -112,6 +112,7 @@ event_trigger <- function(session, event, data = list()) {
 
 #' Wrap an expression that will be executed one time in an event handler
 #'
+#' @description
 #' This wraps an expression so that it will be executed one time for a tutorial,
 #' based on some condition. The first time the condition is true, the expression
 #' will be executed; after that, the expression will not be evaluated again.
@@ -123,17 +124,6 @@ event_trigger <- function(session, event, data = list()) {
 #' A common use for `one_time` is to execute an expression when a section is
 #' viewed for the first time.
 #'
-#' @param session A Shiny session object.
-#' @param cond A condition that is used as a filter. The first time the
-#'   condition evaluates to true, `expr` will be evaluated; after that, `expr`
-#'   will not be evaluated again.
-#' @param expr An expression that will be evaluated once, the first time that
-#'   `cond` is true.
-#' @param label A unique identifier. This is used as an ID for the condition and
-#'   expression; if two calls to `one_time()` uses the same label, there will be
-#'   an ID collision and only one of them will execute. By default, `cond` is
-#'   deparsed and used as the label.
-#'
 #' @examples
 #' \dontrun{
 #' # This goes in a {r context="server-start"} chunk
@@ -154,6 +144,21 @@ event_trigger <- function(session, event, data = list()) {
 #'
 #'
 #' }
+#'
+#' @param session A Shiny session object.
+#' @param cond A condition that is used as a filter. The first time the
+#'   condition evaluates to true, `expr` will be evaluated; after that, `expr`
+#'   will not be evaluated again.
+#' @param expr An expression that will be evaluated once, the first time that
+#'   `cond` is true.
+#' @param label A unique identifier. This is used as an ID for the condition and
+#'   expression; if two calls to `one_time()` uses the same label, there will be
+#'   an ID collision and only one of them will execute. By default, `cond` is
+#'   deparsed and used as the label.
+#'
+#' @return The result of evaluating `expr` (`one_time()` is intended to be
+#'   called within an event handler).
+#'
 #' @export
 one_time <- function(session, cond, expr, label = deparse(substitute(cond))) {
   # This is meant to be called within an event handler, instead of being

R/html-dependencies.R

@@ -1,9 +1,12 @@
 
 #' Tutorial HTML dependency
 #'
-#' @details HTML dependency for core tutorial JS and CSS. This should be included as a
+#' HTML dependency for core tutorial JS and CSS. This should be included as a
 #' dependency for custom tutorial formats that wish to ensure that that
-#' tutorial.js and tutorial.css are loaded prior their own scripts and stylesheets.
+#' `tutorial.js` and `tutorial.css` are loaded prior their own scripts and
+#' stylesheets.
+#'
+#' @return \pkg{learnr}'s HTML dependencies
 #'
 #' @export
 tutorial_html_dependency <- function() {

R/initialize.R

@@ -7,6 +7,9 @@
 #' \pkg{learnr} package. This function is typically called automatically
 #' as a result of using exercises or questions.
 #'
+#' @return If not previously run, initializes knitr hooks and provides the
+#'   required [rmarkdown::shiny_prerendered_chunk()]s to initialize \pkg{learnr}.
+#'
 #' @export
 initialize_tutorial <- function() {
 

R/mock_exercise.R

@@ -3,7 +3,7 @@
 #' Creates an interactive exercise object that can be used in tests without
 #' having to create a learnr tutorial.
 #'
-#' @examples
+#' @examplesIf identical(Sys.getenv("IN_PKGDOWN"), "true")
 #' mock_exercise(
 #'   user_code = "1 + 1",
 #'   solution_code = "2 + 2",
@@ -60,6 +60,8 @@
 #' @param ... Additional chunk options as if there were included in the
 #'   exercise chunk.
 #'
+#' @return An exercise object.
+#'
 #' @describeIn mock_exercise Create a learnr exercise object
 #' @keywords internal
 #' @export

R/mutate_tags.R

@@ -123,8 +123,6 @@ disable_tags <- function(ele, selector) {
 #'
 #' Method to disable all html tags to not allow users to interact with the html.
 #'
-#' @param ele html tag element
-#' @export
 #' @examples
 #' # add an href to all a tags
 #' disable_all_tags(
@@ -133,6 +131,13 @@ disable_tags <- function(ele, selector) {
 #'     htmltools::a()
 #'   )
 #' )
+#'
+#' @param ele html tag element
+#'
+#' @return An \pkg{htmltools} HTML object with appended `class = "disabled"` and
+#'   `disabled` attributes on all tags.
+#'
+#' @export
 disable_all_tags <- function(ele) {
   mutate_tags(ele, "*", disable_element_fn)
 }
@@ -154,6 +159,10 @@ disable_all_tags <- function(ele) {
 #' )
 #'
 #' @inheritParams disable_all_tags
+#'
+#' @return An \pkg{htmltools} HTML object with appropriately appended classes
+#'   such that a tutorial question is marked as the final answer.
+#'
 #' @export
 finalize_question <- function(ele) {
   ele <- disable_all_tags(ele)

R/options.R

@@ -4,6 +4,11 @@
 #' Set various tutorial options that control the display and evaluation of
 #' exercises.
 #'
+#' @examples
+#' if (interactive()) {
+#'   tutorial_options(exercise.eval = TRUE, exercise.timelimt = 10)
+#' }
+#'
 #' @param exercise.cap Caption for exercise chunk (defaults to the engine's icon or the combination of the engine and \code{" code"}).
 #' @param exercise.eval Whether to pre-evaluate the exercise so the reader can
 #'   see some default output (defaults to \code{FALSE}).
@@ -25,6 +30,8 @@
 #' @param exercise.reveal_solution Whether to reveal the exercise solution if
 #'   a solution chunk is provided.
 #'
+#' @return Nothing. Invisibly sets [knitr::opts_chunk] settings.
+#'
 #' @export
 tutorial_options <- function(exercise.cap = NULL,
                              exercise.eval = FALSE,

R/praise.R

@@ -4,6 +4,13 @@
 #' Random praises and encouragements sayings to compliment your question and
 #' quiz experience.
 #'
+#' @examples
+#' random_praise()
+#' random_praise()
+#'
+#' random_encouragement()
+#' random_encouragement()
+#'
 #' @param language The language for the random phrase. The currently supported
 #'   languages include: `en`, `es`, `pt`, `pl`, `tr`, `de`, `emo`, and `testing`
 #'   (static phrases).

R/question_answers.R

@@ -8,6 +8,10 @@
 #' numeric questions, `answer_fn()` can be used to provide a function that
 #' evaluates the student's submission and returns a custom result.
 #'
+#' @examples
+#' answer(32, correct = FALSE)
+#' answer(42, correct = TRUE, message = "The meaning of life.")
+#'
 #' @param text The answer text or value; for selection-type questions this value
 #'   is shown to the user.
 #' @param fn A function used to evaluate the submitted answer. The function is

R/question_methods.R

@@ -24,14 +24,25 @@
 #'
 #'     - Determines how the question is displayed to the users while  the "Try again" screen is displayed.  Usually this function will disable inputs to the question, i.e. prevent the student from changing the answer options. Similar to `question_ui_initialize`, this should should return a shiny UI object that can be displayed using [shiny::renderUI].
 #'
+#' @examples
+#' q <- question(
+#'   "Which package helps you teach programming skills?",
+#'   answer("dplyr"),
+#'   answer("learnr", correct = TRUE),
+#'   answer("base")
+#' )
+#' question_is_correct(q, "dplyr")
+#' question_is_correct(q, "learnr")
+#'
 #' @param question [question] object used
 #' @param value user input value
 #' @param ... future parameter expansion and custom arguments to be used in dispatched s3 methods.
 #'
+#' @return learnr question objects, UI elements, results or server methods.
+#'
 #' @seealso For more information and question type extension examples, please
 #'   see the **Custom Question Types** section of the `quiz_question` tutorial:
 #'   `learnr::run_tutorial("quiz_question", "learnr")`.
-#'
 #' @export
 #' @rdname question_methods
 question_ui_initialize <- function(question, value, ...) {