render_doc: Render an R Markdown document

In mvanhala/rutils: Utility Functions

Render an R Markdown document

Description

render_doc renders an R Markdown in a fresh R process using callr

Usage

render_doc(
  input,
  input_basedir = NULL,
  output_basedir = getOption("rutils.render.output_basedir"),
  output_dir = NULL,
  output_file = NULL,
  output_formats = NULL,
  params = NULL,
  open = FALSE,
  root = rprojroot::is_git_root | rprojroot::is_rstudio_project,
  ...
)

Arguments

input	Input file
input_basedir	Base input directory (optional). If not specified, will be the first subfolder of the input file within the root directory. For example, for input code/folder1/report.Rmd, the default input_basedir will be code.
output_basedir	Base output directory (default takes from the option rutils.render.output_basedir, which is output by default). This should be expressed relative to the root directory.
output_dir	Directly specify the output directory. If specified, takes precedence over output_basedir.
output_file	Optional, the filename of the output file(s). If not provided, the default is the input filename. Any directory part of output_file will be removed. Only the filename part will be used. The output directory is specified using output_basedir or output_dir. Can be provided with or without an extension. The extension will be removed and replaced with the extension determined by output_formats.
output_formats	Optional, a vector of output file formats to which to render. If not provided, html_document is the default. All available R Markdown output formats are supported. In parentheses, the extensions file extensions that will be created are specified. For example, the format github_document will be saved output_file.github.md; the format html_document will be saved as output_file.html. beamer_presentation (.beamer.pdf) context_document (.context.pdf) github_document (.github.md) html_document (.html) ioslides_presentation (.ioslides.html) latex_document (.tex) md_document (.md) odt_document (.odt) pdf_document (.pdf) powerpoint_presentation (.pptx) rtf_document (.rtf) slidy_presentation (.slidy.html) word_document (.docx)
params	Parameters in the R Markdown document to execute
open	Whether to open the output document using rstudioapi::viewer
root	Root criterion using a specification from rprojroot::root_criterion. Determines the root folder.
...	Additional arguments passed to rmarkdown::render

Details

This function assumes you are working within a project structure, specifically an RStudio project. The output file will be saved at the same location relative to output_basedir as input is relative to input_basedir. For example, using the defaults, if the input file is code/folder1/folder2/report.Rmd, the output file will be saved to output/folder1/folder2/report.html. The user may select base input and output directories, relative to which the paths are computed. The user may also directly specify the output directory if preferred.

To use this function in a R Markdown document, you can place the following line in the YAML header:

knit: (function(inputFile, encoding) rutils::render_doc(inputFile))

If rendering to multiple formats, keep in mind that the R code is executed again for each format, as noted here. Therefore, for documents that take a lengthy period of time to run, it may not preferable to render to multiple formats.

mvanhala/rutils documentation built on Feb. 13, 2023, 9:08 a.m.