BookdownUtils: an opinionated approach to building a collaborative bookdown book

Add author name

Add affiliation

Sean Davis

Center for Cancer Research, National Cancer Institute, National Institutes of Health, Bethesda, MD
seandavi@gmail.com
Source: vignettes/bookdown_utils.Rmd

Abstract

Description of your vignette

Overview

The bookdown package can be used to build gitbook books from multiple R markdown documents. The process for doing so is well-documented for a single user with a directory of R markdown documents.

A more complicated use case includes some additional requirements.

  • The materials and R packages required to successfully run the materials in the book should be installable, including dependencies.
  • Book chapters will be authored by individual contributors and each should be able to control when new content is merged into the book while still being able to work independently on their own materials.
  • Contributions from each user should themselves be versioned, coupled to a particular version of the book, and potentially decoupled from the book to include or exclude content.
  • Individual chapters and (and should) be incorporated into individual installable R packages so that R dependencies, code, and extended documentation can be included.
  • The bookdown “parent” repository will depend on the packages from individual contributors. Installing the “parent” repository will lead to versioned installations of each “chapter” repository.

High-level implementation

  • Parent package
    • DESCRIPTION file
      • contains Depends for each chapter package
      • contains Remotes for each chapter package, ideally tied to individual tag, branch, or commit.
    • _bookdown.yml
      • contains rmd_files tag that lists .Rmd file locations–these vignettes will be located in git submodules as described next
    • workshops directory
      • contains git submodules1 for each chapter package

Contributor workflow

Creating the package and vignette

  • Create a normal R package.
  • Create a vignettes directory
  • Create your vignette as PACKAGENAME.Rmd (use same capitalization, etc. as your package name)
  • Create a FOLDER within the vignettes directory named exactly as your package. Place any files specific to your vignettes in that folder (bibliography, images, etc.).
  • When writing your vignette, reference any additional files from the folder above.

Finally, create a soft link between the vignettes directory and the inst directory. For example, in the top level directory of your package do:

mkdir inst
ln -s vignettes inst/vignettes

After this, commit to git if desired. Installing your package will now include the vignette directory and all supporting vignette files. For a package named CoolWorkshopPackage, in R, this code will get to the installed vignette materials:

dir(system.file(package='CoolWorkshopPackage', 'vignettes'))

Editor workflow

  • Create fork of Parent package
  • Do local testing.
  • Pull request.
  • ???? Can we use github actions to perform CI/CD?

HOWTOs

Set up a Parent package

Add a new chapter and chapter package

Update a chapter and chapter package

Build the book

Questions

  • What happens when the vignette contains extra files?
  • What happens with references?
  • Do we need to muck with the yaml front matter before building vignettes?
  • Can/should we use a dotfile in the child chapter packages to signal where the vignette is located, or should we store that detail in the _bookdown.yml file directly?

Authoring notes

Style macros

BiocStyle introduces the following macros for referring to R packages:

  • IRanges, for Bioconductor software, annotation and experiment data packages,
  • data.table, for R packages available on CRAN,
  • rmarkdown, for R packages available on GitHub,
  • MyPkg, for R packages that are not available on Bioconductor, CRAN or GitHub.

Session info

## R Under development (unstable) (2019-01-14 r75992)
## Platform: x86_64-apple-darwin15.6.0 (64-bit)
## Running under: macOS Mojave 10.14.2
## 
## Matrix products: default
## BLAS: /Library/Frameworks/R.framework/Versions/3.6/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/3.6/Resources/lib/libRlapack.dylib
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] BiocStyle_2.11.0
## 
## loaded via a namespace (and not attached):
##  [1] Rcpp_1.0.1         rstudioapi_0.10    knitr_1.22        
##  [4] xml2_1.2.0         magrittr_1.5       roxygen2_6.1.1    
##  [7] MASS_7.3-51.4      R6_2.4.0           rlang_0.3.4       
## [10] stringr_1.4.0      tools_3.6.0        xfun_0.6          
## [13] htmltools_0.3.6    commonmark_1.7     yaml_2.2.0        
## [16] digest_0.6.18      assertthat_0.2.1   rprojroot_1.3-2   
## [19] bookdown_0.9       pkgdown_1.3.0      crayon_1.3.4      
## [22] BiocManager_1.30.4 fs_1.2.7           memoise_1.1.0     
## [25] evaluate_0.13      rmarkdown_1.12     stringi_1.4.3     
## [28] compiler_3.6.0     desc_1.2.0         backports_1.1.3

  1. see a tutorial and git documentation for using git submodules.↩