Package 'tutorizeR'

Render a generated tutorial and return render status

Description

Render a generated tutorial and return render status

Usage

check_tutorial(file, language = c("en", "fr"))

Arguments

file	Path to tutorial '.Rmd' to render.
language	Message language ('"en"' or '"fr"').

Value

Invisibly, the render output path or the error object.

Examples

if (interactive()) {
  check_tutorial("analysis-tutorial.Rmd")
}

---

Convert all '.Rmd'/'.qmd' files in a folder

Description

Converts every matching source file in 'dir', with resilient per-file error handling and a summary report.

Usage

convert_folder(
  dir = ".",
  pattern = "\\.(Rmd|qmd)$",
  recursive = FALSE,
  output_dir = NULL,
  format = c("learnr", "quarto-live"),
  assessment = c("code", "mcq", "both"),
  overwrite = FALSE,
  language = c("en", "fr"),
  seed = NULL,
  verbose = TRUE,
  question_bank = NULL,
  mcq_source = c("inline", "bank", "mixed"),
  lint_strict = FALSE
)

Arguments

dir	Folder containing source files.
pattern	Regex pattern used to select files.
recursive	Logical; recurse into subdirectories?
output_dir	Output directory for generated files.
format	Output format ('"learnr"' or '"quarto-live"').
assessment	Assessment mode ('"code"', '"mcq"', '"both"').
overwrite	Logical; overwrite existing outputs?
language	Message/template language ('"en"' or '"fr"').
seed	Optional integer seed injected in setup chunk.
verbose	Logical; print progress and summary?
question_bank	Optional path(s) or 'tutorize_question_bank' object.
mcq_source	MCQ generation source ('"inline"', '"bank"', '"mixed"').
lint_strict	Logical; fail conversion when lint reports errors.

Value

A 'tutorize_folder_report' object (invisibly).

Examples

labs <- file.path(tempdir(), "labs")
out <- file.path(tempdir(), "tutorials")
dir.create(labs, recursive = TRUE, showWarnings = FALSE)
writeLines(
  c("---", "title: Demo", "---", "", "```{r}", "1 + 1", "```"),
  file.path(labs, "demo.Rmd")
)
report <- convert_folder(labs, output_dir = out, recursive = TRUE, verbose = FALSE)
print(report)

---

Backward-compatible wrapper for tutorial conversion

Description

'convert_to_tutorial()' is kept for compatibility with earlier versions. New code should use [tutorize()].

Usage

convert_to_tutorial(
  input_file,
  output_file = NULL,
  assessment = c("code", "mcq", "both"),
  format = c("learnr", "quarto-live"),
  add_mcq = NULL,
  question_bank = NULL,
  mcq_source = c("inline", "bank", "mixed"),
  lint_strict = FALSE
)

Arguments

input_file	Path to source '.Rmd' or '.qmd' file.
output_file	Output path.
assessment	Assessment mode: '"code"', '"mcq"', or '"both"'.
format	Output format: '"learnr"' or '"quarto-live"'.
add_mcq	Deprecated. Use 'assessment' instead.
question_bank	Optional path(s) or 'tutorize_question_bank' object.
mcq_source	MCQ generation source: '"inline"', '"bank"', '"mixed"'.
lint_strict	Logical; fail conversion when lint reports errors.

Value

Invisibly, the generated output file path.

Examples

input <- tempfile(fileext = ".Rmd")
output <- tempfile(fileext = ".Rmd")
writeLines(c("---", "title: Demo", "---", "", "```{r}", "1 + 1", "```"), input)
convert_to_tutorial(input, output_file = output)

---

Export a profile-aware LMS manifest

Description

Export a profile-aware LMS manifest

Usage

export_lms_manifest(
  input,
  output_file = NULL,
  profile = c("generic", "canvas", "moodle"),
  include_solutions = TRUE,
  language = c("en", "fr")
)

Arguments

input	Source '.Rmd'/'.qmd' file.
output_file	Output path for the manifest file.
profile	Manifest profile ('"generic"', '"canvas"', '"moodle"').
include_solutions	Logical; mark exercise solutions as available.
language	Manifest language ('"en"' or '"fr"').

Value

A 'tutorize_lms_manifest' object.

---

Export a tutorial-ready package scaffold (opt-in)

Description

Export a tutorial-ready package scaffold (opt-in)

Usage

export_tutorial_package(
  input,
  path = NULL,
  package_name = NULL,
  overwrite = FALSE
)

Arguments

input	Source '.Rmd'/'.qmd' file.
path	Parent directory where the package directory will be created.
package_name	Optional package name. Derived from input by default.
overwrite	Logical; replace existing package directory if present.

Value

Invisibly returns the created package path.

---

RStudio Addin: Convert active document to tutorial

Description

Opens a lightweight prompt flow (format, assessment, output directory, overwrite) and converts the currently active file.

Usage

launch_tutorizeR_addin()

Value

Invisibly returns the 'tutorize_report' object, or 'NULL' when cancelled.

---

RStudio Addin: Convert a folder to tutorials

Description

Prompts for folder and conversion options, then converts all matching files.

Usage

launch_tutorizeR_folder_addin()

Value

Invisibly returns a 'tutorize_folder_report' object, or 'NULL' when cancelled.

---

RStudio Addin: Preview conversion with lint and diff

Description

Opens a gadget with Source, Output, Diff, Lint and Logs tabs.

Usage

launch_tutorizeR_preview_addin()

Value

Invisibly returns a 'tutorize_report' object or 'NULL'.

---

Lint source pedagogical constraints before conversion

Description

Lint source pedagogical constraints before conversion

Usage

lint_source(
  input,
  question_bank = NULL,
  language = c("en", "fr"),
  strict = FALSE
)

Arguments

input	Source '.Rmd' or '.qmd' file.
question_bank	Optional 'tutorize_question_bank' object.
language	Message language ('"en"' or '"fr"').
strict	Logical; if 'TRUE', stop when lint errors are present.

Value

A 'tutorize_lint_report' object.

---

Load a reusable MCQ question bank from YAML/JSON files

Description

Load a reusable MCQ question bank from YAML/JSON files

Usage

load_question_bank(
  path,
  recursive = TRUE,
  format = c("auto", "yaml", "json"),
  strict = TRUE,
  language = c("en", "fr")
)

Arguments

path	File or directory path(s) containing question bank files.
recursive	Logical; recurse into subdirectories when 'path' is a directory.
format	Input format: '"auto"', '"yaml"', or '"json"'.
strict	Logical; if 'TRUE', validation errors stop execution.
language	Language for validation messages ('"en"' or '"fr"').

Value

A 'tutorize_question_bank' object.

---

Print method for folder conversion reports

Description

Print method for folder conversion reports

Usage

## S3 method for class 'tutorize_folder_report'
print(x, ...)

Arguments

x	A 'tutorize_folder_report' object.
...	Unused.

Value

'x', invisibly.

---

Print method for lint reports

Description

Print method for lint reports

Usage

## S3 method for class 'tutorize_lint_report'
print(x, ...)

Arguments

x	A 'tutorize_lint_report' object.
...	Unused.

Value

'x', invisibly.

---

Print method for LMS manifest exports

Description

Print method for LMS manifest exports

Usage

## S3 method for class 'tutorize_lms_manifest'
print(x, ...)

Arguments

x	A 'tutorize_lms_manifest' object.
...	Unused.

Value

'x', invisibly.

---

Print method for tutorize conversion reports

Description

Print method for tutorize conversion reports

Usage

## S3 method for class 'tutorize_report'
print(x, ...)

Arguments

x	A 'tutorize_report' object.
...	Unused.

Value

'x', invisibly.

---

Translate a tutorizeR message key

Description

Looks up a message key in language dictionaries and interpolates named placeholders (for example, "{name}").

Usage

tr(key, ..., language = NULL)

Arguments

key	Dot-separated translation key (e.g. '"messages.render_ok"').
...	Named interpolation values.
language	Optional language ('"en"' or '"fr"').

Value

A translated character string.

---

Convert a source document into an interactive tutorial

Description

'tutorize()' is the canonical high-level API. It converts an existing '.Rmd' or '.qmd' source document into a tutorial-ready document for 'learnr' or 'quarto-live'.

Usage

tutorize(
  input,
  output_dir = NULL,
  format = c("learnr", "quarto-live"),
  assessment = c("code", "mcq", "both"),
  overwrite = FALSE,
  language = c("en", "fr"),
  seed = NULL,
  verbose = TRUE,
  output_file = NULL,
  question_bank = NULL,
  mcq_source = c("inline", "bank", "mixed"),
  lint_strict = FALSE
)

Arguments

input	Path to source '.Rmd' or '.qmd' file.
output_dir	Output directory. Required unless 'output_file' is supplied.
format	Output format: '"learnr"' (default) or '"quarto-live"'.
assessment	Assessment mode: '"code"', '"mcq"', or '"both"'.
overwrite	Logical; overwrite existing output file?
language	Message/template language: '"en"' (default) or '"fr"'.
seed	Optional integer seed injected into setup chunk.
verbose	Logical; show progress and diagnostic messages?
output_file	Optional explicit output file path. Useful for wrappers.
question_bank	Optional path(s) or 'tutorize_question_bank' object.
mcq_source	MCQ generation source: '"inline"', '"bank"', '"mixed"'.
lint_strict	Logical; fail conversion when lint reports errors.

Value

A 'tutorize_report' object (invisibly).

Examples

input <- tempfile(fileext = ".qmd")
writeLines(c("---", "title: Demo", "---", "", "```{r}", "1 + 1", "```"), input)
rep <- tutorize(
  input,
  output_dir = tempdir(),
  format = "learnr",
  assessment = "both",
  overwrite = TRUE,
  verbose = FALSE
)
print(rep)

---

Validate tutorizeR input arguments

Description

Performs defensive checks for file path, format, assessment, and extension.

Usage

validate_input(
  input,
  format = c("learnr", "quarto-live"),
  assessment = c("code", "mcq", "both"),
  language = c("en", "fr")
)

Arguments

input	Path to source '.Rmd' or '.qmd' document.
format	Target output format ('"learnr"' or '"quarto-live"').
assessment	Assessment mode ('"code"', '"mcq"', or '"both"').
language	Language for validation messages ('"en"' or '"fr"').

Value

Invisibly returns 'TRUE' if validation succeeds.

---

Validate output path and overwrite strategy

Description

Validate output path and overwrite strategy

Usage

validate_output(
  output_file,
  input_file,
  overwrite = FALSE,
  language = c("en", "fr")
)

Arguments

output_file	Destination output file path.
input_file	Source file path.
overwrite	Logical; allow replacing an existing output.
language	Language for validation messages ('"en"' or '"fr"').

Value

Invisibly returns 'TRUE' if validation succeeds.

---

Validate a 'tutorize_question_bank' object

Description

Validate a 'tutorize_question_bank' object

Usage

validate_question_bank(bank, strict = TRUE, language = c("en", "fr"))

Arguments

bank	A question bank object from [load_question_bank()].
strict	Logical; if 'TRUE', stop on validation errors.
language	Language for validation messages ('"en"' or '"fr"').

Value

A 'tutorize_lint_report' object.

---

Write a conversion report to JSON or YAML

Description

Write a conversion report to JSON or YAML

Usage

write_tutorize_report(report, file, format = c("json", "yaml"), pretty = TRUE)

Arguments

report	A 'tutorize_report' object.
file	Output file path.
format	Output serialization format ('"json"' or '"yaml"').
pretty	Logical; pretty-print JSON output.

Value

Invisibly returns 'file'.

---