From 8af781ad81191dbe09211b09c343fc008425c5f5 Mon Sep 17 00:00:00 2001
From: Garrick Aden-Buie
Date: Tue, 18 Oct 2022 11:40:44 -0400
Subject: [PATCH] v0.11.0 (#735)
Co-authored-by: Alex Rossell Hayes <44556601+rossellhayes@users.noreply.github.com>
---
DESCRIPTION | 2 +-
NEWS.md | 12 +-
R/ace.R | 4 +-
R/debug_exercise_checker.R | 2 +
R/evaluators.R | 11 +-
R/events.R | 27 +-
R/html-dependencies.R | 7 +-
R/initialize.R | 3 +
R/mock_exercise.R | 4 +-
R/mutate_tags.R | 13 +-
R/options.R | 7 +
R/praise.R | 7 +
R/question_answers.R | 4 +
R/question_methods.R | 13 +-
R/quiz.R | 66 +--
R/run.R | 43 +-
R/storage.R | 7 +-
R/tutorial-format.R | 49 +-
R/utils.R | 29 +-
README.Rmd | 4 +-
README.md | 20 +-
cran-comments.md | 45 +-
inst/lib/ace/ace.js | 132 +++--
inst/tutorials/setup-chunks/setup-chunks.Rmd | 67 ++-
man/answer.Rd | 5 +
man/debug_exercise_checker.Rd | 3 +
man/disable_all_tags.Rd | 5 +
man/duplicate_env.Rd | 11 +-
man/external_evaluator.Rd | 6 +-
man/filesystem_storage.Rd | 7 +-
man/finalize_question.Rd | 4 +
man/initialize_tutorial.Rd | 4 +
man/knit_print.Rd | 3 +-
man/mock_exercise.Rd | 6 +-
man/one_time.Rd | 8 +-
man/question_methods.Rd | 14 +
man/quiz.Rd | 7 +-
man/random_praise.Rd | 8 +
man/rmd-fragments/badges.Rmd | 2 +-
man/rmd-fragments/learnr-install.Rmd | 12 +-
man/run_tutorial.Rd | 3 +
man/safe.Rd | 4 +
man/safe_env.Rd | 7 +
man/tutorial.Rd | 7 +
man/tutorial_html_dependency.Rd | 9 +-
man/tutorial_options.Rd | 9 +
pkgdown/_pkgdown.yml | 9 +
pkgdown/extra.css | 14 +
pkgdown/index.md | 26 +-
pkgdown/templates/content-article.html | 63 +++
tools/update-ace.R | 2 +-
vignettes/.gitignore | 1 +
vignettes/articles/examples.Rmd | 15 +
vignettes/articles/examples.yml | 57 +++
.../articles/images/create-new-tutorial.png | Bin 172277 -> 86218 bytes
.../images/example-community-afrilearnr.png | Bin 0 -> 104008 bytes
.../images/example-community-dosstoolkit.png | Bin 0 -> 198853 bytes
.../example-community-learntidymodels.png | Bin 0 -> 240242 bytes
.../images/example-community-qsslearnr.png | Bin 0 -> 241296 bytes
.../images/example-community-rtledu.png | Bin 0 -> 61905 bytes
vignettes/articles/images/exercise-blanks.png | Bin 48994 -> 31377 bytes
vignettes/articles/images/exercise-code.png | Bin 83382 -> 47175 bytes
.../articles/images/exercise-completion.png | Bin 52250 -> 31582 bytes
vignettes/articles/images/exercise-error.png | Bin 83723 -> 47498 bytes
vignettes/articles/images/exercise-result.png | Bin 68938 -> 35286 bytes
vignettes/articles/images/exercises.png | Bin 186366 -> 115538 bytes
vignettes/articles/images/format-tutorial.png | Bin 173849 -> 94543 bytes
vignettes/articles/images/question-math.png | Bin 42366 -> 23311 bytes
vignettes/articles/images/question.png | Bin 35912 -> 21013 bytes
.../articles/images/questions-message.png | Bin 41540 -> 24356 bytes
vignettes/articles/images/questions.png | Bin 83690 -> 45102 bytes
.../images/shinyapps-deploy-faithful.png | Bin 164636 -> 126722 bytes
vignettes/articles/images/slidy.png | Bin 151052 -> 109136 bytes
vignettes/articles/images/solution.png | Bin 54540 -> 40703 bytes
.../images/tutorial-ex-data-basics.png | Bin 111075 -> 69257 bytes
.../images/tutorial-ex-data-filter.png | Bin 168779 -> 109959 bytes
.../images/tutorial-ex-data-mutate.png | Bin 145714 -> 94308 bytes
.../images/tutorial-ex-data-summarise.png | Bin 169045 -> 118033 bytes
.../articles/images/tutorial-ex-setup-r.png | Bin 127446 -> 91014 bytes
.../images/tutorial-external-sortable.png | Bin 101455 -> 62357 bytes
vignettes/articles/images/tutorial-hello.png | Bin 48251 -> 25294 bytes
.../images/tutorial-quiz_question.png | Bin 130586 -> 83415 bytes
vignettes/articles/images/tutorial-slidy.png | Bin 131788 -> 95688 bytes
vignettes/articles/images/tutorial-sql.png | Bin 159240 -> 93335 bytes
.../releases/images/blanks-warning-custom.png | Bin 0 -> 45490 bytes
.../releases/images/blanks-warning.png | Bin 0 -> 47728 bytes
.../releases/images/error-checker.png | Bin 0 -> 44620 bytes
.../releases/images/exercise-tab-example.gif | Bin 0 -> 212031 bytes
.../releases/images/exercise-tab-example.mp4 | Bin 0 -> 49700 bytes
.../releases/images/fancy-quotes-warning.png | Bin 0 -> 74213 bytes
.../janko-ferlic-sfL_QOnmy00-unsplash.jpg | Bin 0 -> 213052 bytes
.../releases/images/question-numeric.png | Bin 0 -> 11063 bytes
.../releases/images/r-python-exercise.png | Bin 0 -> 45661 bytes
.../releases/images/syntax-warning.png | Bin 0 -> 51294 bytes
.../articles/releases/learnr_v0-11-0.Rmd | 472 ++++++++++++++++++
vignettes/shinyapps-publishing.Rmd | 2 +-
96 files changed, 1117 insertions(+), 266 deletions(-)
create mode 100644 pkgdown/templates/content-article.html
create mode 100644 vignettes/articles/images/example-community-afrilearnr.png
create mode 100644 vignettes/articles/images/example-community-dosstoolkit.png
create mode 100644 vignettes/articles/images/example-community-learntidymodels.png
create mode 100644 vignettes/articles/images/example-community-qsslearnr.png
create mode 100644 vignettes/articles/images/example-community-rtledu.png
create mode 100644 vignettes/articles/releases/images/blanks-warning-custom.png
create mode 100644 vignettes/articles/releases/images/blanks-warning.png
create mode 100644 vignettes/articles/releases/images/error-checker.png
create mode 100644 vignettes/articles/releases/images/exercise-tab-example.gif
create mode 100644 vignettes/articles/releases/images/exercise-tab-example.mp4
create mode 100644 vignettes/articles/releases/images/fancy-quotes-warning.png
create mode 100644 vignettes/articles/releases/images/janko-ferlic-sfL_QOnmy00-unsplash.jpg
create mode 100644 vignettes/articles/releases/images/question-numeric.png
create mode 100644 vignettes/articles/releases/images/r-python-exercise.png
create mode 100644 vignettes/articles/releases/images/syntax-warning.png
create mode 100644 vignettes/articles/releases/learnr_v0-11-0.Rmd
diff --git a/DESCRIPTION b/DESCRIPTION
index 1b2ed7a80..446234f32 100644
--- a/DESCRIPTION
+++ b/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", , "garrick@rstudio.com", role = c("aut", "cre"),
comment = c(ORCID = "0000-0002-7111-0077")),
diff --git a/NEWS.md b/NEWS.md
index cd350ca2d..5a7167351 100644
--- a/NEWS.md
+++ b/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
diff --git a/R/ace.R b/R/ace.R
index 271db4981..454944bc3 100644
--- a/R/ace.R
+++ b/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")
diff --git a/R/debug_exercise_checker.R b/R/debug_exercise_checker.R
index 48c97f1aa..fedd30c3d 100644
--- a/R/debug_exercise_checker.R
+++ b/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,
diff --git a/R/evaluators.R b/R/evaluators.R
index d8445b3a5..86a5c7d57 100644
--- a/R/evaluators.R
+++ b/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)
}
diff --git a/R/events.R b/R/events.R
index da56ec7d7..bfbec6799 100644
--- a/R/events.R
+++ b/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
diff --git a/R/html-dependencies.R b/R/html-dependencies.R
index 8ddaffe5b..e32cb9c8c 100644
--- a/R/html-dependencies.R
+++ b/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() {
diff --git a/R/initialize.R b/R/initialize.R
index 68d757313..b1ecdd9b4 100644
--- a/R/initialize.R
+++ b/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() {
diff --git a/R/mock_exercise.R b/R/mock_exercise.R
index a63960efb..5fd5e1d76 100644
--- a/R/mock_exercise.R
+++ b/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
diff --git a/R/mutate_tags.R b/R/mutate_tags.R
index 2daa4a38e..8de830056 100644
--- a/R/mutate_tags.R
+++ b/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)
diff --git a/R/options.R b/R/options.R
index 0055b51c4..690e66d98 100644
--- a/R/options.R
+++ b/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,
diff --git a/R/praise.R b/R/praise.R
index 410e95ae8..477d06637 100644
--- a/R/praise.R
+++ b/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).
diff --git a/R/question_answers.R b/R/question_answers.R
index cddce2fbf..28b624edf 100644
--- a/R/question_answers.R
+++ b/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
diff --git a/R/question_methods.R b/R/question_methods.R
index 6b80f7d76..6ee78e6bf 100644
--- a/R/question_methods.R
+++ b/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, ...) {
diff --git a/R/quiz.R b/R/quiz.R
index 5fbf35367..e969e7448 100644
--- a/R/quiz.R
+++ b/R/quiz.R
@@ -30,10 +30,27 @@
#' structure and information will be displayed.
#'
#'
-#' @seealso For more information and question type extension examples, please
-#' see the help documentation for [question_methods][question_ui_initialize()]
-#' and view the \code{question_type} tutorial:
-#' `learnr::run_tutorial("question_type", "learnr")`.
+#' @examples
+#' quiz(
+#' question("What number is the letter A in the alphabet?",
+#' answer("8"),
+#' answer("14"),
+#' answer("1", correct = TRUE),
+#' answer("23"),
+#' incorrect = "See [here](https://en.wikipedia.org/wiki/English_alphabet) and try again.",
+#' allow_retry = TRUE
+#' ),
+#'
+#' question("Where are you right now? (select ALL that apply)",
+#' answer("Planet Earth", correct = TRUE),
+#' answer("Pluto"),
+#' answer("At a computing device", correct = TRUE),
+#' answer("In the Milky Way", correct = TRUE),
+#' incorrect = paste0("Incorrect. You're on Earth, ",
+#' "in the Milky Way, at a computer.")
+#' )
+#' )
+#'
#' @param text Question or option text
#' @param ... One or more questions or answers
#' @param caption Optional quiz caption (defaults to "Quiz")
@@ -70,30 +87,14 @@
#' useful when using custom question types. See [sortable::question_rank()]
#' for an example question implementation that uses the `options` parameter.
#'
-#' @examples
-#' quiz(
-#' question("What number is the letter A in the alphabet?",
-#' answer("8"),
-#' answer("14"),
-#' answer("1", correct = TRUE),
-#' answer("23"),
-#' incorrect = "See [here](https://en.wikipedia.org/wiki/English_alphabet) and try again.",
-#' allow_retry = TRUE
-#' ),
-#'
-#' question("Where are you right now? (select ALL that apply)",
-#' answer("Planet Earth", correct = TRUE),
-#' answer("Pluto"),
-#' answer("At a computing device", correct = TRUE),
-#' answer("In the Milky Way", correct = TRUE),
-#' incorrect = paste0("Incorrect. You're on Earth, ",
-#' "in the Milky Way, at a computer.")
-#' )
-#' )
-#'
-#' @seealso [random_praise()], [random_encouragement()]
+#' @return A learnr quiz, or collection of questions.
#'
#' @family Interactive Questions
+#' @seealso [random_praise()], [random_encouragement()]
+#' @seealso For more information and question type extension examples, please
+#' see the help documentation for [question_methods][question_ui_initialize()]
+#' and view the \code{question_type} tutorial:
+#' `learnr::run_tutorial("question_type", "learnr")`.
#' @name quiz
#' @rdname quiz
#' @export
@@ -288,11 +289,14 @@ shuffle <- function(x) {
#' Knitr quiz print methods
#'
-#' \code{knitr::\link[knitr]{knit_print}} methods for \code{\link{question}} and \code{\link{quiz}}
+#' \code{knitr::\link[knitr]{knit_print}} methods for \code{\link{question}} and
+#' \code{\link{quiz}}
+#'
#' @inheritParams knitr::knit_print
-#' @export
+#'
#' @importFrom knitr knit_print
#' @method knit_print tutorial_question
+#' @export
#' @rdname knit_print
knit_print.tutorial_question <- function(x, ...) {
question <- x
@@ -311,6 +315,7 @@ knit_print.tutorial_question <- function(x, ...) {
# regular knit print the UI
knitr::knit_print(ui)
}
+
#' @method knit_print tutorial_quiz
#' @export
#' @rdname knit_print
@@ -735,9 +740,10 @@ question_messages <- function(question, messages, is_correct, is_done) {
}
question_ui_loading <- function(question) {
- n_paragraphs <- max(length(str_match_all(question$question, "