R-de.po for German translations of lesson elements
(@martin-raden #607)<code>
(reported: @abostroem, #562; fixed @froggleston)inLanguage key.vignette("translations", package = "sandpaper")R/utils-translate.R). This will make finding and updating these strings
easier for maintainer and translators.these$translations?translate contains details of how
translations of template elements are rendered.tr_src() helper function provides access to the source strings of the
translations.tr_get(), tr_varnish(), and tr_computed() helper functions provide
access top the lists of translated strings. These have replaced the tr_()
strings at the point of generation.known_languages() is a function that will return the language codes that are
known by {sandpaper}.vignette("translation", package = "sandpaper") describes how
translation of template components works and how to submit new/update
translations (added: @zkamvar, #546).vignette("data-flow", package = "sandpaper")
describes how templating, translations, and lesson metadata flows from
{sandpaper} to {varnish} (added: @zkamvar, #553)handout: true in config.yaml will cause a handout to be generated
for the lesson website under /files/code-handout.R. At the moment, this is
only relevant for R-based lessons (implemented: @froggleston, #527,
reviewed: @zkamvar) and supersedes the need for specifying
options(sandpaper.handout = TRUE)create_episode() will now open new episodes for editing in interactive
sessions (implemented: @milanmlft, #534, reviewed: @zkamvar)site/ folder is now customisable to any writable directory on your
system by setting the experimental SANDPAPER_SITE environment variable to
any valid and empty folder. This is most useful in the context of Docker
containers, where file permissions to mounted volumes are not always
guaranteed (reported: @fherreazcue #536; implemented: @zkamvar, #537)doi: key to the config.yaml file with either the raw DOI or
the URL to the DOI (reported: @tobyhodges, carpentries/workbench#67;
fixed: @tobyhodges, #535).build_status() function: make sure root_path() always points
to lesson root (reported: @milanmlft, #531; fixed: @milanmlft, #532)mailto: links are no longer prepended with the URL (reported: @apirogov,
#538; fixed: @zkamvar, #539)files, fig, and data
folders with the cautionary note that duplicate file names to other folders
will cause an error.validate_lesson() now reports invalid elements of child documentsvignette("include-child-documents", package = "sandpaper")
demonstrates and describes the caveats about using child documents.setup.md will now be reflected in the website.
(reported: @tobyhodges, @fnattino, and @zkamvar, #521; fixed: @ErinBecker and
@zkamvar, #522).init.defaultBranch declarations in their git config
will no longer fail the default branch check (reported: @tesaunders, #516;
fixed: @zkamvar, #517)images.html will no longer fail if there
is an episode that starts with images-) (reported: @mwhamgenomics, #511;
fixed: @zkamvar, #512)overview: true to your config.yaml (reported: @zkamvar,
https://github.com/carpentries/workbench/issues/65;
implemented: @zkamvar, #496)spoiler class of fenced div will allow authors to specify an
expandable section of content that is collapsed by default. This replaces the
former paradigm of using "floating solution" blocks to present options for
installation on different platforms. (implemented: @tobyhodges, #502)root_path() will no longer fail if the episodes/ folder
does not exist as long as one of the other four folders (site/, learners/,
instructors/, profiles/) exists (fixed: @zkamvar, #496)set_config() can now properly process logical values into true and falsesandpaper:::check_pandoc() now points to the correct
URL to download RStudio, which moved after the migration to posit (@zkamvar,
#471)sandpaper:::render_html() now explicitly sets the
pandoc version before running the subprocess. This allows lesson developers to
use the {pandoc} package to set their pandoc versions. (reported: @zkamvar,
#465; fixed: @zkamvar, #465)sandpaper::serve() gains the quiet argument, defaulting to TRUE for
interactive sessions and FALSE for command line sessionssandpaper::serve() gains the ... argument to pass options to
servr::server_config() for setting ports and hosts (reported:
@twrightsman, https://github.com/carpentries/workbench/issues/50 and #459;
fixed: @zkamvar, #461).sandpaper::serve() has been
fixed (reported: @zkamvar, #450; fixed: @zkamvar, #451)callr::r() as an intermediary
(reported: @zkamvar, #442, fixed: @zkamvar, #452)ci_ functions (reported: @zkamvar, #430; fixed: @zkamvar,
#431).sandpaper::serve() will no longer error if a different directory is used.create-pull-request action is now coming from a fork in The Carpentries
organisation for security.update_cache() will now work with {renv} version 0.17.1, which lost a
print method for the renv_updates class (reported: @zkamvar, #415;
fixed: @zkamvar, #416 and
https://github.com/zkamvar/vise/commit/ee4798701a958ee48429980eb970266885f8265blearners/resources.md, which will allow the
glossary link to work (reported: @elichad, #404 and
@ManonMarchand,
https://github.com/carpentries/workbench-template-md/issues/20;
fixed: @zkamvar, #410)renv::diagnostics() during building of R Markdown
documents has been suppressed.message_package_cache() no longer fails with {renv}
version 0.17.0.manage_deps() will now attempt to recover errors from "missing" bioconductor
packages. Note that this is a provisional solution because it treats
BioConductor packages as an afterthought. The full fix for this should be
when {renv} bootstraps BioConductor repositories (reported: @zkamvar, #365 and
https://github.com/rstudio/renv/issues/1110; fixed: @zkamvar, #397)update_cache() and pin_version() will now find the root path of the
lesson before checking and manipulating dependencies. This will circumvent
the issue where a user could accidentally create a episodes/renv folder by
running update_cache() from the episodes/ directory (discovered:
@sarahkaspar; reported: @zkamvar, #391; fixed: @zkamvar, #392).learners: field in config.yaml
(reported: @zkamvar, #386; fixed: @zkamvar #387).pandoc.Null() constructor for Lua filters (reported:
@zkamvar, #380; fixed: @zkamvar: #385)pr-recieve.yaml and
pr-comment.yaml are given separate concurrency parameters based on the
branch name and the pull request number. These concurrencies will prevent
false alarms as found in
https://github.com/carpentries/lesson-development-training/pull/165#issuecomment-1337182275.
(discovered: @anenadic; reported: @zkamvar, #374; fixed: @zkamvar, #376)The create_syllabus() function no longer uses pkgdown::as_pkgdown() and
assumes a flat file structure when creating the syllabus. This provides a
further fix for #371.
The downlit shim has been updated to modify the function bodies while preserving the function signatures.
workflows for testing on Windows has been fixed by setting the git config
autocrlf to false before checkout (thanks to @assignUser for the tip).
The test coverage workflow has been updated to avoid long build times.
build_ functions cleaned up. Unused variables removed
and narrative comments added to provide context.public_repo scope.pandoc is now set to use the default version for r-lib/setup-pandoc (at the time of this update, it is version 2.19.2.
Workflows that update workflows and packages will now push to single branches
called update/workflows and update/packages, respectively. This will avoid
the issue with #350
Workflows no longer use the deprecated set-output command (reported:
@zkamvar, #349; fixed @zkamvar, #356)
Versions of external actions have been updated to include actions/[email protected]
move_episode(),
set_episode(), etc) will now display a message if the user does not specify
write = TRUE. This message will present a command that, when executed, will
make the desired change (requested: @tobyhodges, #345, fixed: @zkamvar, #352)source config parameter will have the trailing / trimmed off when
passed to the site so that the URL does not have two consectutive slashes.renv/sandbox no longer required in .gitignore. A new bug introduced in
0.10.2 caused all lessons built before 0.10.2 to fail when rebuilt on CI.
This was due to the assumption that the .gitignore item renv/sandbox was
strictly necessary with no clear method to automatically update a file like
this (reported: @zkamvar, #347; fixed: @zkamvar, #348).sandpaper-version.txt in version 0.8.0 inside the
workflow templates folder was causing workflow update script to create pull
requests for the workflows every week when they should have been much less
frequent (the irony of this commit is that it will trigger another pull
request) (fixed: @zkamvar, #346)..gitignore now has renv/sandbox to avoid a sandbox directory
from being tracked by git. (see https://github.com/rstudio/renv/issues/1088)
(reported: @zkamvar; #344, fixed: @zkamvar, #343)deploy-aws.yaml workflow has been removed as plans for its use is
relegated to the beta stage of the workbench.index.md (or Rmd) file has a title YAML element, this will take
precedence over the default title of "Summary and Setup".
(requested: @SaraMorsy, #339; fixed: @zkamvar #342)create_episode() and create_lesson() is to use
episodes without numbered prefixes and will now automatically add episodes
to the schedule (requested: @tobyhodges, #330; fixed @zkamvar, #333)move_episode() allows the lesson contributor to move an episode
in the schedule (requested: @tobyhodges, #330, fixed: @zkamvar, #333)draft_lesson_md() and draft_lesson_rmd() perform the task of
create_lesson(add = FALSE).strip_prefix() will automatically strip the prefixes for all
episodes in the schedule.get_config() now has a default path argument.link_attributes has been added to process custom link
classes (see https://pandoc.org/MANUAL.html#extension-link_attributes for
details).set_dropdown()set_config() gains the option create, which will create new variables if
they do not exist.deploy-aws.yaml has been created to deploy a site to
AWS when the right secrets from AWS are available. Because this workflow
does not affect normal use, I am relegating this to a patch release.A new workflow called pr-preflight.yaml has been created to perform a quick
pre-flight check on the pull request to ensure that there is no malicious
activity on the lesson itself, which may look like modifying both workflow
and lesson files in the same pull request. For lessons that transition to the
workbench from styles in official and community-developed lessons, an extra
check is added that will validate the branch of the incoming PR does not
contain invalid commits.
Pull Request workflows have been simplified.
fail_on_error defaulted to true has been fixed. This will
default to false if they key is not present in config.yaml (#314, @zkamvar).fail_on_error: true in config.yaml will set the global chunk
option error = FALSE for R Markdown documents, meaning that if an error
is produced from a chunk, the build will fail unless that chunk explicitly
uses the error = TRUE option. (requested: #306 by @davidps, implemented:
#310 by @zkamvar)config.yaml template has been updated to default to incubator lessons
and has more helpful information included about formatting (@tobyhodges, #302)create_lesson() gains the rmd parameter, which is a logical indicator that
the lesson should use R Markdown (TRUE by default). When this is FALSE, a
markdown lesson is created and no package cache is initialised.create_episode() gains the ext parameter, which allows users to create
plain markdown episodes if they do not need R Markdown functionality
(see https://github.com/carpentries/sandpaper/issues/296).create_episode() will now slugify titles so that they only contain lowercase
ASCII letters, numbers and UTF-8 characters with words separated by single
hyphens (see https://github.com/carpentries/sandpaper/issues/294).check_episode() function has been removed as it was over-
engineered with marginal value.{{#yaml}} context.set_dropdown() will preserve the yaml items that are not
explicitly coded in the config menu.build_episode_md() argument workenv now defaults to globalenv() to avoid
S3 dispatch issues that can occur in new.env() (see https://github.com/carpentries/sandpaper/issues/288)setup-r and setup-pandoc actions have been pinned to version 2setup-r action now uses the default R installation on GitHub's runner,
which decreases build times by ~ 1 minute.images.html is built with internal function build_images(), collecting
all images and displaying alt text for non-screen reader users (while
marking those paragraphs as aria-hidden so that screen reader users do not
have it read twice).instructor-notes.html is now built with the internal function
build_instructor_notes() and now collects instructor notes from the
episodes in a section called aggregate-instructor-notes.build_agg_page() has a new argument, append, which takes an
XPath expression of what node should have children appended. Defaults to
"self::node()". An example of alternate usage is in
build_instructor_notes(), which uses
section[@id='aggregate-instructor-notes'].build_agg_page() (build aggregate
page). This allows slow templating processes to be performed once and cached
instead of repeated for each page. It provides a framework for future
aggregate pages (such as figures, instructor notes, glossary, etc).quiet = FALSE./aio.html and
instructor/aio.html.this_lesson(), which is run
during validate_lesson(). This simplifies the setup a bit, and provides the
same method of cache invalidation (checking git outputs) for all of these
elementskeypoints.html is now rendered as key-points.html to fix navigation error
with varnish.index.html#setup (@zkamvar, #262)links.md. If this file exists, it will be concatenated on each
markdown file before it is rendered to HTML. Thanks to @sstevens2 for bringing
this feature up (@zkamvar, #257)create_lesson() now includes links.md in main directory.?sandpaper.options provides documentation on the
global options used in a sandpaper lesson (subject to change).validate_lesson() will perform checks on links and fenced divs in your
lesson. This is now included in calls to build_lesson(), ci_deploy() and
serve() (@zkamvar, #255)this_lesson() will now properly invalidate and reset if
there is a change in commit (e.g. the lesson to build has switched).set_dropdown() no longer fails with {cli} version 3.2.0sandpaper::build_lesson() no longer creates an infinite loop when called
after sandpaper::serve() (@zkamvar, #247)@type
as TrainingMaterial (@zkamvar, #236)render_html() now passes the --preserve-tabs
parameter to prevent pandoc from removing educationally relevant information
from the lessons.ci_deploy(..., rebuild = TRUE), detritus in
the lesson site will be cleaned (@zkamvar, #91).There are now two views of the lesson: instructor view and learner view. The
biggest difference is that instructor view gains the instructor-note sections
(if they exist).
The only downside at the moment is that building the lesson takes a bit longer due to the fact that we now have to render two pages for each change.
A persistant sidebar with links for the main content of the lesson will be present on all pages of the lesson. The navigation bar will prioritise items used most frequently by the respective audiences:
keywords: item where you can
place a comma-separated list of keywords to include in the site's metadatarenv_cache_available() continues to work with {renv}
0.15.0. This new version of {renv} changed the default value of a
configuration setting for the system cache from a logical to NULL, which
casued a logical operation to fail. (@zkamvar, #223)serve() now allows you to work on your lesson and have it automatically
rebuild whenever you save your files to disk.serve() function.build_handout() is now an officially exported function.ubuntu-latest instead of macOS-11.
The macOS runners were often ~ 1 minute faster than the ubuntu runners, but
the tradeoff was potential failures when packages were not available as
binary versions and would need compilation with external C libraries (along
with runs failing due to brew timeouts). This update coincides with an update
for the github actions, which will now check and install the ubuntu
dependencies before updating/installing packages. (@zkamvar, #184)set_config() now takes a named vector/list instead of a pair of vectors.eval.expr = FALSE
in all yaml parsing calls.update-cache.yaml has been fixed to run strictly on the
first Tuesday of the month instead of the first seven days of the month AND on
Tuesdays.update-cache.yaml has been simplified to pull from the carpentries/actions
repository and now updates packages that were not previously included in the
lockfile (#185).update-cache.yaml has been fixed from a regression introduced with
4b8b14d088d03a8a9c6c90e974bb53c35691fb49 where the workflow would not run
because it did not check out the repository beforehand.update_github_workflows() now sets clean = "*.yaml" by default to align
with the behavior of the GitHub workflow and to prevent stale workflows from
being present in the repository. (#181, @zkamvar)sandpaper-main.yaml and pr-receive.yaml have been simplified by using
composite actions hosted in carpentries/actions/setup-sandpaper and
carpentries/actions/setup-deps.CACHE_VERSION.manage_deps() runs slightly faster now that it no longer runs
renv::hydrate() if no new packages have been added in the lesson.option(sandpaper.handout = TRUE) will create a code handout for R
lessons that will live in /files/code-handout.R on your site.pegboard::Lesson objects
that we use for extracting components for the syllabus and the handout. See
?lesson_storage for details.pr-receive.yaml has fixed spelling.pr-receive.yaml has changed to short-cut the invalid PR messages and no
longer build the lesson if the PR is invalid. Instead, it will emit the same
warning message without building artifacts.pr-comment.yaml will no longer fail when no artifacts exist (which would
cause extraneous emails for users).The template for the pull request message reverts back to two-dot diff notation between branches, which is temporary until #169 can be addressed. Linebreaks within paragraphs have been removed to avoid github formatting them as linebreaks.
This update for {sandpaper} brings in dependency management for lessons with generated content which will make collaboration between these lessons much easier and less invasive by establishing a package cache and lockfile via the {renv} R package.
We use the {renv} package for controlling dependency management in the lesson, which is contained in a {renv} profile called "lesson-requirements". We have implemented this as a profile instead of the default {renv} environment to give the maintainers flexibility of whether or not they want to use the package cache.
getOption('sandpaper.use_renv') will be set when {sandpaper} loads to
detect if the contributor has previously consented to use the {renv} package.
If this is TRUE, the lesson will use a package cache, otherwise, the lesson
will use the default library.use_package_cache() will give consent to {sandpaper} to create and use a
package cache via {renv}. Internally, this enforces that
options(sandpaper.use_renv = TRUE).no_package_cache() does the opposite of use_package_cache() and revokes
consent to use the package cache in a lesson temporarily. This can be useful
in situtations where the cache is mis-behaving or you want to test the lesson
using a newer set of packages. Internally, this enforces that
options(sandpaper.use_renv = FALSE).package_cache_trigger(TRUE) allows you to trigger a full rebuild when the
lockfile changes. This is set to TRUE by default on ci_build_markdown()manage_deps() is a new function that will manage dependencies for a lesson.
This is called both in create_lesson() and build_markdown() to ensure
that the correct dependencies for the lesson are installed. This explicitly
calls use_package_cache() when it runs.update_cache() will bring in updates for the lesson cache.pin_version() will pin packages to a specific version, allowing authors to
upgrade or downgrade packages at will.create_lesson() now additionally will create a {renv} profile called
"packages" in the lesson repository if getOption('sandpaper.use_renv') is
TRUE. This will make the lesson more portable.ci_deploy() will set sandpaper.use_renv option to
TRUEbuild_markdown() and thus build_lesson() will now cache config.yaml and
renv.lock. It will no longer step through the build process if no markdown
files need to be rebuilt. This will cause any project built with previous
versions of sandpaper to be fully rebuilt.sandpaper_site() (and thus, build_lesson()) now can take in a single file
for rendering and render that specific file regardless if it is present in
the cache without rendering other files. This further addresses #77. (n.b.
this involved changes to build_markdown(), build_site(), and
build_status()).varnish_vars() is a list that contains commonly used variables in the
lesson that can not be contained in the config.yamlbuild_episode() and build_home() now supply default variables to varnish.ci_deploy() will now automatically check and set the
git user and email.sandpaper-main.yaml and pr-receive.yaml have been updated to include
the {renv} cache, but they will skip these steps for markdown lessons.update-cache.yaml is a new workflow that will update the package cache
lockfile and create a pull request to trigger new builds if the lesson uses
{renv}.update-workflows.yaml now produces more informative instructions for
creating a repository secret.config.yaml are now reflected on the lesson site without
rebuilding (fixes #75)root.dir has been set to the output directory to avoid
generated content from entering the source.This is a placeholder for the testing of 0.0.0.9050.
update-workflows.yaml workflow now checks if the SANDPAPER_WORKFLOW
secret is valid. If not, it provides instructions for creating a new secret.update-workflow.yaml parameters have been fixed to not use wildcardsupdate_github_workflows() gains a clean argument and now will print
status reports at the end.update-workflow.yaml workflow has been updated to use the github action
hosted on zkamvar/actions (soon to be transferred to The Carpentries accountinst/scripts/update-workflows.sh has been removed in favor of
the github action.update-workflow.yaml workflow has been created which will
create a pull request that will update the workflows. It is still very
experimental and it requires a scoped with repo and scope, but,
nevertheless, the concept is currently valid.fetch_github_workflows() has been renamed to update_github_workflows()create_lesson() now reports progress as it goes alongci_deploy() gains the reset argument, which can be used to clear the
cache for a clean build of the lesson.ci_deploy() now uses ci_build_markdown() and ci_build_site(),
internallyci_session_info() will report the session information, which will help
clean up the workflow files.ci_bundle_pr_artifacts() no longer escapes HTML-like output in
the diff summary.git_worktree_setup() has been added for future versions
of the maintainer and future contributors.ci_bundle_pr_artifacts() is a new internal function that will create
artifacts for GitHub to upload upon receipt of a pull request. This will
replace clunky shell code that lived inside a YAML configuration file.
(@zkamvar, #139)learners/setup.md in
episodes/introduction.md, you would write [setup](../learners/setup.md)
and it will be automatically converted to the correct URL in the website
(#43). This is still backwards compatible with the previous iteration of
writing the flattened link (as it would appear on the website).get_drafts() will report any markdown files that are not currently
published in the lesson."sandpaper.show_draft"
option. To turn off these messages, use
options(sandpaper.show_draft = FALSE)set_dropdown() family of functions will now throw an error if an
author attempts to add a file that does not existconfig.yaml do not exist in the
lesson with an informative message highlighting the files that are missing.get_resource_list() function has been modified to incorporate
the features of get_dropdown(). This means that all get_dropdown()
functions will only report the files in the dropdown menus that actually
exist in the directory (#134).warn_schedule() function has
been changed exclusively use cli messages and can be suppressed with
suppressMessages().sandpaper_cli_theme() is used to style CLI messages.The {pingr} package is now being imported to check for online access, which will marginally decrease data usage (@fmichonneau, #127).
create_schedule() (internal function) no longer uses pegboard's extensions
for fixing reference links.create_lesson() will now enforce "main" or the default branch (if
init.defaultBranch is set) as the default branch for the new lesson. It will
also try to make the URL match the project name and user name (but the latter
is limited to users who have GitHub PAT set up that {gh} recognises).build_episode_md() now sets the knitr.pandoc.to knit option to allow for
the chunk option fig.cap to be rendered as a caption. This fixes #114.set_dropdown() is now generalized to set any item in the dropdown menu
(though this will likely be wrapped into a better-named function for
generalized editing).system.file("transform.R", pacakge = "sandpaper") points to a file that
will be used for transforming styles-repo era lessons to sandpaper lessons.build_markdown(rebuild = TRUE) now actually rebuilds the lessonbuild_markdown() trying to clean after building the output instead
of before. It's a situation of throwing the baby out with the bathwater. In
any case, this fixes #102.instructor/ and profile/ menus. This fixes #103.set_*() functions no longer mess up yaml lists in config.yaml. This
fixes #53.create_episode() with make_prefix = FALSE will no longer create episodes
prefixed with - (see #93).fetch_github_workflows() will download and update the GitHub workflows from
the Carpentries actions repository.update_varnish() will download and update the {varnish} styling package to
your local repository.The caching mechanism is now similar to that of {blogdown} where a database of source files and their checksum hashes is kept and only the updated files are built. This provides two advantages, the first is that we no longer have to peek at the top of the files to check if they need to be updated and the second is that we can keep the files in the right order (see #85)
Importantly, the workflow itself should not be affected, but there will be changes in what gets displayed on the github diff of the md-outputs branch.
sandpaper_site() is a site generator function that allows {rmarkdown} to
use the {sandpaper} machinery to build the site from
rmarkdown::render_site()build_site() gains a slug argument that tailors the previewed content.create_lesson() will now create a blank index.md with site: sandpaper_site as the only YAML item.index.md exists at the top level, it will be used instead of README.md
for the lesson index page (fix #56).{SOURCE}-rendered- in the
site/built/fig/ subdir.HTML will now be processed with pandoc lua filters that will do the following:
<aside> tagsREADME updated to reflect API changes
Continuous integration functions added:
ci_deploy() will build the markdown source and the site and commit them to
separate branches, including information about their source.ci_build_markdown() will build the markdown source files and commit them
to a separate branch, including information about the source commit.ci_build_site() will build the site directly from the markdown branch,
bypassing re-rendering the markdown files.Miscellaneous additions
build_site() compartmentalizes the conversion from
markdown to html.git in the episodes directory will not be
copied over to the website._schedule() functions have been renamed to _episodes().clean_*() functions are now renamed to reset_*()set/get/reset_dropdown() functions have been created to facilitate
modification/access of folders that are dropdown menus inside of the lessonbuild_markdown() will now generate artifacts in the site/built/assets/
directory instead of episodes/ directory to prevent generated artifacts from
being included in git (See https://github.com/carpentries/sandpaper/issues/24)html_from_md() renamed to render_html()build_episode() renamed to build_episode_html() and exported,
but documentation still internalbuild_single_episode() renamed to build_episode_md() and exported,
but documentation still internalbuild_markdown() due to being called in a separate process
was fixed.build_markdown()build_lesson() will now render HTML in episode titles.override argument to build_lesson(). This gets passed on to
pkgdown::as_pkgdown() for more control over where the site gets built.