ci_build: Build and deploy individual site components to a remote...

In zkamvar/sandpaper: Create and Curate Carpentries Lessons

Build and deploy individual site components to a remote branch

Description

These are the internal functions which provision and deploy lesson components to orphan git branches. These are called by ci_deploy(). These functions have the side-effect of creating and updating orphan branches on a remote repository. It is assumed that you have access to your remote.

Usage

ci_build_markdown(
  path = ".",
  branch = "md-outputs",
  remote = "origin",
  reset = FALSE
)

ci_build_site(
  path = ".",
  branch = "gh-pages",
  md = "md-outputs",
  remote = "origin",
  reset = FALSE
)

Arguments

path	path to the lesson
branch	the branch name containing the output: ci_build_markdown(): defaults to md-output, corresponds to md_branch in ci_deploy() ci_build_site(): defaults to gh-pages, corresponds to site_branch in ci_deploy()
remote	the name of the git remote to which you should deploy.
reset	if TRUE, the markdown cache is cleared before rebuilding, this defaults to FALSE meaning the markdown cache will be provisioned and used.
md	the branch name that contains the markdown outputs

Details

The only place these two functions are used are within ci_deploy(), which has the de-facto use-case for these functions, thus, this page has no examples. Both of these functions do the same general process:

1. provision a git worktree in the appropriate folder with git_worktree_setup()

2. build the requisite content in that folder

3. commit and push the contents to the worktree with github_worktree_commit()

There are caveats for each of the two functions as listed in the sections below.

ci_build_markdown()

This will not clean up after itself by default. You must save the output in an object and run eval(obj) to run the clean up process. This is in place so that ci_build_site() can use the worktree from the markdown outputs in order to build the site.

ci_build_site()

In addition to the steps listed above, this function needs to verify that it has the materials necessary to build the HTML site.

It first checks for the presence of ⁠site/built/⁠. This folder can be generated by ci_build_markdown() or by build_markdown(). If the folder does not exist or it is empty, then this function will attempt to fetch the folder from the branch in md.

Once everything is built and pushed, this function will additionally destroy the work tree.

Value

• ci_build_markdown(): an expression() that is evaluated to tear down the worktree that was created.

• ci_build_site(): nothing, it is used for its side-effect.

Note

ci_build_markdown() will set the sandpaper.use_renv option to TRUE, which means that it will always use the {renv} package cache if the lesson uses R Markdown.

zkamvar/sandpaper documentation built on Feb. 2, 2025, 5:17 p.m.