Purl Rmd/*.Rmd to R/*.gen.R

This function strives to provide a standardized way to convert all relevant .Rmd files in the Rmd/ subdirectory to bare .R files in the R/ subdirectory using knitr::purl(). It is mainly intended for authoring R packages in the R Markdown file format.

Usage

purl_rmd(
  path = ".",
  add_copyright_notice = pal::pkg_config_val(key = "add_copyright_notice", pkg =
    this_pkg, default = TRUE),
  add_license_notice = pal::pkg_config_val(key = "add_license_notice", pkg = this_pkg,
    default = TRUE),
  gen_pkgdown_ref = pal::pkg_config_val(key = "gen_pkgdown_ref", pkg = this_pkg, default
    = TRUE),
  env = parent.frame()
)

Arguments

path

Path to the root of the package directory.

add_copyright_notice

Whether or not to add a copyright notice at the beginning of the generated .R files as recommended by e.g. the GNU licenses. The notice consists of the name and description of the program and the word Copyright (C) followed by the release years and the name(s) of the copyright holder(s), or if not specified, the author(s). The year is always the current year. All the other information is extracted from the package's DESCRIPTION file. A logical scalar. Only applies if path is actually an R package directory.

add_license_notice

Whether or not to add a license notice at the beginning of the generated .R files as recommended by e.g. the GNU licenses. The license is determined from the package's DESCRIPTION file and currently only the AGPL-3.0-or-later license is supported. A logical scalar. Only applies if path is actually an R package directory.

gen_pkgdown_ref

Whether or not to overwrite pkgdown's reference index in the configuration file _pkgdown.yml with an auto-generated one based on the main input file as described in gen_pkgdown_ref(). A logical scalar. Only applies if path is actually an R package directory, pkgdown is set up and a main R Markdown file exists.

env

Environment to evaluate R Markdown inline code expressions in when generating the pkgdown reference index. Only relevant if gen_pkgdown_ref = TRUE.

Value

path, invisibly.

Details

The generated .R files will be named the same as the .Rmd files plus the suffix .gen to indicate the file was auto-generated. So the file Rmd/foo.Rmd for example will be converted to R/foo.gen.R.

The R Markdown file format allows you to intermingle code with related prose in Markdown syntax optimized for human readability. This facilitates (best) practices which are commonly referred to as literate programming.

In practice, the main advantage of writing R code in R Markdown is that you don't have to rely on # comments to explain, annotate or otherwise elaborate on your code. It also allows you to easily compile your source code to beautifully looking HTML, PDF etc. files using rmarkdown::render().

This function is also registered as an RStudio add-in, allowing RStudio users to assign a custom shortcut to it or to invoke it from the command palette.

.Rmd files excluded from purling

purl_rmd() does not generate an .R file for each and every R Markdown file in the Rmd/ subdirectory. Two types of .Rmd files are excluded from purling:

1. Files having the suffix .nopurl in their name, e.g. Rmd/playground.nopurl.Rmd.

2. Hidden files as per Unix convention whose names start with a dot, e.g. Rmd/.playground.Rmd.

The above convention allows for easy exclusion of specific .Rmd files from purling. A common case for this are scripts that generate package-internal data from raw sources. Such a script could be stored as Rmd/data.nopurl.Rmd, so that no corresponding file under R/*.R is generated. For the sake of clarity, it's generally advised to prefer the .nopurl suffix over hiding files.

See also

Other high-level functions: lint_rmd(), load_pkg(), process_pkg(), run_nopurl_rmd()