Merge pull request #599 from LearnToDiscover/milanmlft/fix-checkRd-notes

Fix `checkRd` notes

DESCRIPTION

@@ -109,7 +109,7 @@ Config/testthat/parallel: false
 Config/Needs/check: rstudio/renv
 Config/potools/style: explicit
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.2
 URL: https://carpentries.github.io/sandpaper/, https://github.com/carpentries/sandpaper/, https://carpentries.github.io/workbench/
 BugReports: https://github.com/carpentries/sandpaper/issues/
 VignetteBuilder: knitr

NAMESPACE

@@ -37,6 +37,7 @@ export(set_instructors)
 export(set_learners)
 export(set_profiles)
 export(strip_prefix)
+export(template_citation)
 export(template_conduct)
 export(template_config)
 export(template_contributing)

R/build_episode.R

@@ -1,7 +1,7 @@
 #' Build a single episode html file
 #'
 #' This is a Carpentries-specific wrapper around [pkgdown::render_page()] with
-#' templates from {varnish}. This function is largely for internal use and will
+#' templates from `{varnish}`. This function is largely for internal use and will
 #' likely change.
 #'
 #' @param path_md the path to the episode markdown (not RMarkdown) file
@@ -165,7 +165,7 @@ get_nav_data <- function(path_md, path_src = NULL, home = NULL,
 #' @param workenv an environment to use for evaluation. Defaults to the global
 #'   environment, which evaluates to the environment from [callr::r()].
 #' @param quiet if `TRUE`, output is suppressed, default is `FALSE` to show
-#'   {knitr} output.
+#'   `{knitr}` output.
 #' @param error if `TRUE` (default) errors do not make an invalid build.
 #'   This can be set to false to cause the build to fail if an error occurs.
 #'   This is generally controlled via the `fail_on_error` config option.

R/build_home.R

@@ -15,7 +15,7 @@
 #'   2. learners/setup.md
 #'
 #' This function uses [render_html()] to convert the page into HTML, which gets
-#' passed on to the "syllabus" or "overview" templates in {varnish} (via the
+#' passed on to the "syllabus" or "overview" templates in `{varnish}` (via the
 #' [build_html()] function as the `{{{ readme }}}` and `{{{ setup }}}` keys.
 build_home <- function(pkg, quiet, next_page = NULL) {
   page_globals <- setup_page_globals()

R/build_html.R

@@ -1,6 +1,6 @@
 #' Build instructor and learner HTML page
 #'
-#' @param template the name of the {varnish} template to use. Defaults to
+#' @param template the name of the `{varnish}` template to use. Defaults to
 #'   "chapter"
 #' @param pkg an object created from  [pkgdown::as_pkgdown()]
 #' @param nodes an `xml_document` object. `nodes` will be a list of two
@@ -9,7 +9,7 @@
 #'   and learner page, it will be a single `xml_document` object.
 #' @param global_data a list store object that contains copies of the global
 #'   variables for the page, including metadata, navigation, and variables for
-#'   the {varnish} templates.
+#'   the `{varnish}` templates.
 #' @param path_md the path (absolute, relative, or filename) the current
 #'   markdown file being processed.
 #' @param quiet This parameter is passed to [pkgdown::render_page()] and will
@@ -20,7 +20,7 @@
 #'
 #' @details This function is a central workhorse that connects the global
 #' lesson metadata and the global variables for each page to the rendering
-#' engine: {pkgdown}. It will perform the global operations that includes
+#' engine: `{pkgdown}`. It will perform the global operations that includes
 #' setting up the navigation (via [update_sidebar()]), adding metadata, and
 #' building both the instructor and learner versions of the page (via
 #' [pkgdown::render_page()]).

R/build_lesson.R

@@ -91,13 +91,13 @@ build_lesson <- function(path = ".", rebuild = FALSE, quiet = !interactive(), pr
   #
   # Once we know we have all of the lesson components, we can build the markdown
   # sources and store them in `site/built`. Only the markdown sources that have
-  # changed in content will be rebuilt with {knitr}.
+  # changed in content will be rebuilt with `{knitr}`.
   built <- build_markdown(path = path, rebuild = rebuild, quiet = quiet, slug = slug)
 
   # Building the HTML ----------------------------------------------------------
   #
   # This step uses the contents of `site/built` to build the website in
-  # `site/docs` with {whisker} and {pkgdown}
+  # `site/docs` with {whisker} and `{pkgdown}`
   build_site(path = path, quiet = quiet, preview = preview, override = override, slug = slug, built = built)
 
 }

R/build_markdown.R

@@ -1,7 +1,7 @@
 #' Build plain markdown from the RMarkdown episodes
 #'
-#' In the spirit of {hugodown}, This function will build plain markdown files
-#' as a minimal R package in the `site/` folder of your {sandpaper} lesson
+#' In the spirit of `{hugodown}`, This function will build plain markdown files
+#' as a minimal R package in the `site/` folder of your `{sandpaper}` lesson
 #' repository tagged with the hash of your file to ensure that only files that
 #' have changed are rebuilt.
 #'
@@ -114,7 +114,7 @@ build_markdown <- function(path = ".", rebuild = FALSE, quiet = FALSE, slug = NU
   }
   cli::cli_end()
 
-  # Update hash of {renv} file if it exists ------------------------------------
+  # Update hash of `{renv}` file if it exists ------------------------------------
   if (getOption("sandpaper.use_renv")) {
     hash <- renv_lockfile_hash(path, db_path)
     lf_hash <- fs::path_file(db$new$file) == "renv.lock"

R/ci_build.R

@@ -13,7 +13,7 @@
 #'   - `ci_build_site()`: defaults to `gh-pages`, corresponds to `site_branch`
 #'      in [ci_deploy()]
 #' @note `ci_build_markdown()` will set the `sandpaper.use_renv`
-#'   option to TRUE, which means that it will _always_ use the {renv}
+#'   option to TRUE, which means that it will _always_ use the `{renv}`
 #'   package cache if the lesson uses R Markdown.
 #' @returns
 #'  - `ci_build_markdown()`: an [expression()] that is evaluated to tear down

R/create_episode.R

@@ -11,7 +11,7 @@
 #' @param make_prefix a logical. When `TRUE`, the prefix for the file will be
 #'   automatically determined by the files already present. When `FALSE`
 #'   (default), it assumes no prefix is needed.
-#' @param path the path to the {sandpaper} lesson.
+#' @param path the path to the `{sandpaper}` lesson.
 #' @param add (logical or numeric) If numeric, it represents the position the
 #'   episode should be added. If `TRUE`, the episode is added to the end of the
 #'   schedule. If `FALSE`, the episode is added as a draft episode.

R/create_lesson.R

@@ -97,7 +97,7 @@ create_lesson <- function(path, name = fs::path_file(path), rmd = TRUE, rstudio
 
   cli::cli_status_update("{cli::symbol$arrow_right} Committing ...")
   gert::git_add(".", repo = path)
-  gert::git_commit(message = "Initial commit [via {sandpaper}]", repo = path)
+  gert::git_commit(message = "Initial commit [via `{sandpaper}`]", repo = path)
   enforce_main_branch(path)
   reset_git_user(path)
 

R/get_drafts.R

@@ -1,6 +1,6 @@
 #' Show files in draft form
 #'
-#' By default, {sandpaper} will use the files in alphabetical order as they are
+#' By default, `{sandpaper}` will use the files in alphabetical order as they are
 #' presented in the folders, however, it is **strongly** for authors to specify
 #' the order of the files in their lessons, so that it's easy to rearrange or
 #' add, split, or rearrange files. 

R/manage_deps.R

@@ -35,8 +35,8 @@
 #'   projects on their computer where the package versions are necessary for
 #'   their work, it's important that those environments are respected.
 #'
-#'   Our flavor of {renv} applies a package cache explicitly to the content of
-#'   the lesson, but does not impose itself as the default {renv} environment.
+#'   Our flavor of `{renv}` applies a package cache explicitly to the content of
+#'   the lesson, but does not impose itself as the default `{renv}` environment.
 #'
 #'   This provisioner will do the following steps:
 #'

R/options.R

@@ -35,20 +35,20 @@
 #' ### sandpaper.use_renv
 #'
 #' **Default: variable** This option should not be modified by the user. It
-#' determines if {renv} should be used locally for R-based lessons. It is set
+#' determines if `{renv}` should be used locally for R-based lessons. It is set
 #' by [use_package_cache()] and unset by [no_package_cache()]. If a local user
-#' has never consented to using {renv} previously, then it defaults to `FALSE`,
-#' but if {renv} has previously been used, it will be `TRUE`.
+#' has never consented to using `{renv}` previously, then it defaults to `FALSE`,
+#' but if `{renv}` has previously been used, it will be `TRUE`.
 #'
 #' ### sandpaper.package_cache_trigger
 #'
 #' **Default: FALSE locally/TRUE on GitHub** this tells R Markdown lessons to
-#' rebuild everything if the {renv} lockfile changes. 
+#' rebuild everything if the `{renv}` lockfile changes. 
 #' 
 #' ### sandpaper.test_fixture 
 #'
 #' **Default: NULL** This is ONLY for internal use for testing interactive
-#' components non-interactively and for setting {renv} to behave correctly while
+#' components non-interactively and for setting `{renv}` to behave correctly while
 #' testing. 
 #'
 #' @name sandpaper.options

R/package_cache.R

@@ -53,7 +53,7 @@
 #'
 #' ## I have used \pkg{renv} before; how do I turn it off before sandpaper loads?
 #'
-#' You can set `options(sandpaper.use_renv = FALSE)` before loading {sandpaper}.
+#' You can set `options(sandpaper.use_renv = FALSE)` before loading `{sandpaper}`.
 #'
 #' @param prompt if `TRUE` (default when interactive), a prompt for consent
 #'   giving information about the proposed modifications will appear on the
@@ -68,7 +68,7 @@
 #'   inside the package cache.
 #' @examples
 #' if (!getOption("sandpaper.use_renv") && interactive()) {
-#'   # The first time you set up {renv}, you will need permission
+#'   # The first time you set up `{renv}`, you will need permission
 #'   use_package_cache(prompt = TRUE)
 #'   # The package cache trigger is FALSE, by default
 #'   default <- package_cache_trigger()
@@ -79,7 +79,7 @@
 #' }
 #'
 #' if (getOption("sandpaper.use_renv") && interactive()) {
-#'   # If you have previously used {renv}, permission is implied
+#'   # If you have previously used `{renv}`, permission is implied
 #'   use_package_cache(prompt = TRUE)
 #'
 #'   # You can temporarily turn this off

R/set_dropdown.R

@@ -119,8 +119,8 @@ set_dropdown <- function(path = ".", order = NULL, write = FALSE, folder) {
 #' - **overview** `[boolean]` All lessons must have episodes with the exception
 #'   of overview lessons. To indicate that your lesson serves as an overview for
 #'   other lessons, use `overview: true`
-#' - **handout** `[boolean]` or `[character]` This option instructs {sandpaper}
-#'   to create a handout of all RMarkdown files via {pegboard}, which uses
+#' - **handout** `[boolean]` or `[character]` This option instructs `{sandpaper}`
+#'   to create a handout of all RMarkdown files via `{pegboard}`, which uses
 #'   [knitr::purl()] in the background after removing everything but the
 #'   challenges (without solutions) and any code blocks where `purl = TRUE`. The
 #'   default path for the handout is `files/code-handout.R`

R/template.R

@@ -42,7 +42,7 @@ copy_template <- function(template, path = NULL, name = NULL, values = NULL) {
 #' @export
 #' @keywords internal
 #' @return a character string with the path to the template within the
-#'   {sandpaper} repo. 
+#'   `{sandpaper}` repo. 
 #' @examples
 #'
 #' cat(readLines(template_gitignore(), n = 6), sep = "\n")

R/test-fixtures.R

@@ -2,7 +2,7 @@
 #'
 #' @description
 #'
-#' This suite of functions are for use during testing of {sandpaper} and are
+#' This suite of functions are for use during testing of `{sandpaper}` and are
 #' designed to create/work with a temporary lesson and associated remote
 #' repository (locally) that persists throughout the test suite. These functions
 #' are used in `tests/testthat/setup.R`. For more information, see the [package

R/update_workflows.R

@@ -1,6 +1,6 @@
 #' Update github workflows
 #'
-#' This function copies and updates the workflows to run {sandpaper}. 
+#' This function copies and updates the workflows to run `{sandpaper}`. 
 #'
 #' @param path path to the current lesson.
 #' @param files the files to include in the update. Defaults to an empty string, 

R/utils-git.R

@@ -2,7 +2,7 @@ has_git <- function() {
   Sys.which("git") != ""
 }
 
-# Shamelessly stolen from {pkgdown}, originally authored by Hadley Wickam
+# Shamelessly stolen from `{pkgdown}`, originally authored by Hadley Wickam
 git <- function (..., echo_cmd = TRUE, echo = TRUE, error_on_status = TRUE) {
   if (!has_git()) stop(cli::format_error("{.pkg git} is not installed"), call. = FALSE)
   callr::run("git", c(...), echo_cmd = echo_cmd, echo = echo,
@@ -229,7 +229,7 @@ message_source <- function(commit_message = "", source_branch = "main", dir = ".
   log <- gert::git_log(ref = source_branch, max = 1L, repo = dir)
   paste0(commit_message,
     "\n",
-    "\nAuto-generated via {sandpaper}\n",
+    "\nAuto-generated via `{sandpaper}`\n",
     "Source  : ", log$commit, "\n",
     "Branch  : ", source_branch, "\n",
     "Author  : ", log$author, "\n",

R/utils-renv.R

@@ -1,6 +1,6 @@
 #nocov start
 # very internal function for me to burn everything down. This will remove
-# the local library, local cache, and the entire {renv} cache.
+# the local library, local cache, and the entire `{renv}` cache.
 renv_burn_it_down <- function(path = ".", profile = "lesson-requirements") {
   callr::r(function(path, profile) {
     wd <- getwd()
@@ -22,7 +22,7 @@ renv_is_allowed <- function() {
 
 renv_should_rebuild <- function(path = ".", rebuild, db_path = "site/built/md5sum.txt", profile = "lesson-requirements") {
   return_early <- rebuild            || # if rebuild is TRUE OR
-    !getOption("sandpaper.use_renv") || # if we are not using {renv} OR
+    !getOption("sandpaper.use_renv") || # if we are not using `{renv}` OR
     !package_cache_trigger()            # if the lockfile does not trigger rebuilds
 
   if (return_early) return(rebuild)
@@ -54,16 +54,16 @@ renv_lockfile_hash <- function(path, db_path, profile = "lesson-requirements") {
   return(list(old = old_hash, new = new_hash))
 }
 
-#' Try to use {renv}
+#' Try to use `{renv}`
 #'
 #' We use this when sandpaper starts to see if the user has previously consented
-#' to {renv}. The problem is that [renv::consent()] throws `TRUE` if the user
+#' to `{renv}`. The problem is that [renv::consent()] throws `TRUE` if the user
 #' has consented and an error if it has not :(
 #'
 #' This function wraps `renv::consent()` in a callr function and transforms the
 #' error into `FALSE`. It sets the `sandpaper.use_renv` variable to the value of
 #' that check and then returns the full text of the output if `FALSE` (this is
-#' the WELCOME message that's given when someone uses {renv} for the first time)
+#' the WELCOME message that's given when someone uses `{renv}` for the first time)
 #' and the last line of output if `TRUE` (a message either that a directory has
 #' been created or that consent has already been provided.)
 #'
@@ -235,8 +235,8 @@ callr_manage_deps <- function(path, repos, snapshot, lockfile_exists) {
   options(renv.config.user.profile = FALSE)
   renv_lib  <- renv::paths$library(project = path)
   renv_lock <- renv::paths$lockfile(project = path)
-  # Steps to update a {renv} environment regardless of whether or not the user
-  # has initiated {renv} in the first place
+  # Steps to update a `{renv}` environment regardless of whether or not the user
+  # has initiated `{renv}` in the first place
   #
   # 1. find the packages we need from the global library or elsewhere, and
   #    load them into the profile's library

R/utils-store.R

@@ -2,7 +2,7 @@
 #'
 #' @description
 #' A storage cache for [pegboard::Lesson] objects and other pre-computed items
-#' for use by other internal functions while {sandpaper} is working.
+#' for use by other internal functions while `{sandpaper}` is working.
 #'
 #' @section Lesson Object Storage:
 #'
@@ -22,7 +22,7 @@
 #'   previously stored lesson.
 #'
 #'   The storage cache is in a global package object called `.store`, which is
-#'   initialised when {sandpaper} is loaded via `.lesson_store()`
+#'   initialised when `{sandpaper}` is loaded via `.lesson_store()`
 #'
 #'   If there have been no changes git is aware of, the lesson remains the same.
 #'
@@ -190,7 +190,7 @@ clear_resource_list <- function(path) {
       .this_status <<- gert::git_status(repo = path)
       .this_commit <<- gert::git_log(repo = path, max = 1L)$commit
       .this_lesson <<- pegboard::Lesson$new(path, jekyll = FALSE)
-      # set the global storage for {varnish} so that we do not have to recompute
+      # set the global storage for `{varnish}` so that we do not have to recompute
       # things like the sidebar
       set_globals(path)
       # kludge to make sure overview status is accurate
@@ -253,7 +253,7 @@ template_check <- create_template_check()
 .html <- .list_store()
 
 # storage for global variables for the lesson site (those that get passed on to
-# {varnish})
+# `{varnish}`)
 instructor_globals <- .list_store()
 learner_globals <- .list_store()