guidence/PackageTesting.md

In markanewman/stormdown: PhD dissertation template for Harrisburg University in R Markdown

Testing the Package

Good science is based on reproducibility. Good engineering is the same; we call it testing. The following steps can be taken by a developer to rebuild the package. If you are a user, the standard instalation procedure is what you want. The testing guidance is Windows-centric, but similar steps should run on Mac or Linux.

Local testing

1. Setup the prerequisites.
   • R (3.6.3) + R Studio (1.2.5033)
   • RTools (3.5.0.4)
   • I recommend using Chocolatey, but you can use any method you like. Open a Powershell prompt in admin mode and run the below commands.

if('Unrestricted' -ne (Get-ExecutionPolicy)) { Set-ExecutionPolicy Bypass -Scope Process -Force }
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
refreshenv
choco install r.project --version=3.6.3 -y
refreshenv
choco install r.studio --version=1.2.5033 -y
choco install rtools --version=3.5.0.4 -y

1. Open up [R Studio]rstudio
2. Install the R packages: rmarkdown (2.3), pagedown (0.12), tinytex (0.24), devtools (2.3.0), roxygen2 (7.1.0), kableExtra (1.1.0), dplyr (1.0.0), and ggpubr (0.3.0).
   • roxygen2 is only needed as part of the build process.
   • kableExtra, rlang, dplyr, and ggpubr are only used in the sample sections. You only need them to test the inital Knit.
   • In order to pin the version of the packages, set the repo to a snapshot version.

r <- getOption('repos')
r['CRAN'] <- 'https://mran.microsoft.com/snapshot/2020-06-24'
options(repos = r)
install.packages(c('rmarkdown', 'pagedown', 'tinytex'))
install.packages(c('devtools', 'roxygen2'))
install.packages(c('kableExtra', 'dplyr', 'ggpubr'))
rstudioapi::restartSession()

1. Install LaTeX. There will be a couple of popups complaining about missing DLLs, ignore those.

tinytex::install_tinytex()

1. Restart [R Studio][rstudio] then run the following to test the LaTeX install.

tinytex:::is_tinytex()

1. Clone the repo from GitHub and switch to that folder. The cloned location can be anything you want. I used D:/repos/markanewman so you may need to change the path in some of the following steps. Downloading the zip and extracting it to D:/repos/markanewman should also work just fine.

setwd('D:/repos/markanewman')

1. Clean then compile the stormdown package

package <- 'stormdown'
package_path <- paste0('./', package)
unlink(paste0(package_path, c('/man', '/NAMESPACE')), recursive = T)
devtools::document(package_path)
devtools::check(package_path)
rstudioapi::restartSession()

1. (re)Install the package

lib <- library()
if(package %in% lib$results[,'Package']) { remove.packages(package) }
devtools::install(package_path, dep = T, upgrade = 'never')
rstudioapi::restartSession()

1. Create drafting directories

working_dir <- getwd()
draft_dir <- paste0(working_dir, '/draft')
if (dir.exists(draft_dir)) {
    unlink(draft_dir, recursive = T)}
dir.create(draft_dir, showWarnings = F)
template_names <- c('dissertation')
for(i in 1:length(template_names)) {
    dir.create(paste0(draft_dir, '/t', i), showWarnings = F)}

1. Generate the templates

for(i in 1:length(template_names)) {
    rmarkdown::draft(
        paste0(draft_dir, '/t', i, '/', template_names[i]),
        template = template_names[i],
        package = package,
        create_dir = F,
        edit = F)}

1. Compile the templates. Make sure to use a new enviroment because this more closely resembles the end user clicking the knit button

for(i in 1:length(template_names)) {
    setwd(paste0(draft_dir, '/t', i))
    env_t <- new.env()
    rmarkdown::render(paste0(template_names[i], '.rmd'), envir = env_t)
}
exists <- T
for(i in 1:length(template_names)) {
    exists <- exists & file.exists(paste0(draft_dir, '/t', i, '/', template_names[i], '.html'))}
exists

1. Review the files
2. Cleanup

setwd(working_dir)
unlink(draft_dir, recursive = T)
rm(list=ls())
rstudioapi::restartSession()

Docker Testing

1. Setup the prerequisites.
   • Docker Desktop
   • I recommend using Chocolatey, but you can use any method you like. Open a Powershell prompt in admin mode and run the below commands.

if('Unrestricted' -ne (Get-ExecutionPolicy)) { Set-ExecutionPolicy Bypass -Scope Process -Force }
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
refreshenv
choco install docker-desktop -y

1. Clone the repo from GitHub
2. Run Docker Desktop
3. Open a regular Powershell prompt
4. Switch to the package folder. The cloned location can be anything you want. I used D:/repos so you may need to change the path in some of the following steps.

d:
cd d:/repos/markanewman/stormdown

1. Build the docker image then make and run a container-based off of that image

docker build -t stormdown:local .
docker run --name my_stormdown stormdown:local

1. Copy the generated PDFs out of the container

docker cp my_stormdown:/draft/t1/dissertation.html dissertation.html

1. Review the PDFs
2. Cleanup

docker rm my_stormdown
docker rmi stormdown:local

markanewman/stormdown documentation built on Jan. 1, 2021, 9:18 a.m.