2 Overview

The litr package consists of (a) document templates that users can use as the basis for creating an R package, (b) code needed so that when such a R markdown file is knitted, it will generate not just an .html (or some other output format) but also an R package. The code has the following components:

  1. Functionality for generating the R package when the .Rmd file is knitted. In particular, we define a knitr chunk hook, which we call send_to_package() that identifies code chunks in the .Rmd file that should be included in the package. To make it so that this chunk hook will be active, we also have a function called setup() that is called at the start of litr::render() right before rmarkdown::render() is called. The setup() function makes it so that when the .Rmd file is knitted, the chunk hook send_to_package() will be invoked on each code chunk. It is also responsible for other preliminaries, such as defining a new knitr language engine that can interpret package-level documentation.

  2. Functionality for making sure the R package outputted will not overwrite a manually edited R package. Our approach here is to use a hash that will make it clear whether something has been modified.

  3. Wrapper to devtools::document() The reason we write a wrapper for devtools::document() is because we want it to behave slightly differently. In particular, devtools::document() reminds the reader to edit the roxygen in the R/ files, whereas in our case, we want to make sure they edit the original .Rmd file, not the R/ files.

  4. Functionality to alter the rendering process The focus here is to make it so that all the special litr functionality will be active when the .Rmd is rendered. We implement two ways this can happen. First, we have several custom output formats, such as litr_html_document(). When rmarkdown::render() is called with one of these litr output formats, setup() gets called before knitting occurs and some other litr-specific post-processing occurs as well. The second way is through the function litr::render(). If a user calls litr::render() with a non-litr output format, e.g. rmarkdown::html_document(), then setup() gets called before rmarkdown::render() and also post-processing can again happen. Another thing of note about litr::render() is that it renders the document in a fresh environment, which ensures identical behavior to when a user presses “Knit” in RStudio.