bookdown source code refactoring

[Albert Y. Kim]

A running list of all bookdown source code refactoring to be done by 2020/7/1:

Setup

• Pare down _bookdown.yml so that bookdown only builds index & chapter of interest. This will speed book building

Edit setup chunk

• Make setup chunk consistent with new Ch3 setup. In particular, set all code chunk defaults as below. I think they all are consistent, but copy/paste with caution nonetheless in case there are differences.

# Set R code chunk defaults:
knitr::opts_chunk$set(
  echo = TRUE,
  eval = TRUE,
  warning = FALSE,
  message = TRUE,
  tidy = FALSE,
  purl = TRUE,
  out.width = "\\textwidth",
  fig.height = 4,
  fig.align = "center"
)

All other chunks

Setting options

• Only set chunk options when they are counter to defaults. In other words, the code chunk options code should be as minimal as possible. Ex: since eval=TRUE was set as default in setup chunk, all eval=TRUE should be removed in subsequent chunks.

R code chunk purl() management

We create .R script files of the R Markdown code in each chapter by running knitr::purl(), which get saved in docs/scripts. That way users can have a single file of only R code. We need to ensure that each .R script file only includes relevant outward-facing code.

For each code chunk:

• Whenever include=FALSE, purl=FALSE no question.
• Whenever it is a learning check block, purl=FALSE no question.
• Updated decision rule for all other cases: As pointed out by @mariumtapal, it should not be based on combinations of settings of echo or eval, rather the more simple "do we want the user to run this code in the console/R Markdown or not".
• Whenever echo=FALSE, it depends
  • If code chunk is "isolate", then purl=FALSE no question.
  • If code chunk is preceded by a code block where eval = FALSE, then purl=TRUE. i.e. we present one set of code to the user, but use slightly different code for the output in the actual book. Ex: code shown to user to create regression tables vs formatted regression tables for book using kable_styling()
• Whenever eval=FALSE, it depends.
  • Sometimes code won't run at all. Ex: x %>% f() %>% g(). Here set purl=FALSE.
  • Other times code is relevant, but we set eval = FALSE b/c it would break bookdown build. Ex: View(flights). Here set purl=TRUE

Obsessive lily gilding clean up

• Replace all ' with ". Ex: replace all type='learncheck' with type=“learncheck”
• Code chunk options set with no spaces. Ex: eval=FALSE and not eval = FALSE

Run styler

• On every non-outward facing chunks, clean code using styler. i.e. run RStudio -> Addins -> "Style selection", run on code chunks where echo=FALSE or include=FALSE. Outward facing code should be left intact, otherwise moderndive.com and print edition will be misaligned.

Before/after comparison

• At the end of refactoring each chapter, open both moderndive.com version and your local version and do a comparison to ensure outward facing content is the same. One way to do this: open each in side-by-side browser windows, and scroll thru using spacebar to ensure the sections are the same lenght.