In R, the fundamental unit of shareable code is the package.
— Chapter 1 Introduction | R Packages
If you're sharing report templates with colleagues, one option is to make a small package to hold those reports. If the end user only needs to set the parameters to render the report — i.e. if they do not need to edit the report contents — you could even provide a wrapper function around rmarkdown::render(). That would let you document the parameters in the same way as function parameters.
#' Render result report
#'
#' Render a fancy result report
#'
#' @inheritParams rmarkdown::render
#' @inheritDotParams rmarkdown::render
#' @param res_file Path to results file generated by script `generate_results.R`
#' @param gs_species Organisms. Use binomial species nomenclature, currently
#' only Homo sapiens is accepted
#' @param gs_category Which categories, as listed in the
#' <https://example.com/categories.html>
#' @param gmt_file Path to file containing things
#' @param extra_sets Path to file containing one set per line. Use the set names
#' listed in the site <https://example.com/categories.html>
#' @param gs_string Used for partial matching of sets. When you are too lazy to
#' look the site above.
#' @param padjCutoff Where to draw the line of what matters
#'
#' @return Writes the report to `output_file`
#' @export
render_result_report <- function(
output_file,
res_file,
gs_species = "Homo sapiens",
gs_category = c("All", "Option 1", "Option 2"),
gmt_file = NULL,
extra_sets = NULL,
gs_string = NULL,
padjCutoff = 0.1,
...
) {
stopifnot(identical(gs_species, "Homo sapiens"))
gs_category <- match.arg(gs_category)
# other input checking
params <- list(
res_file = res_file,
gs_species = gs_species,
gs_category = gs_category,
gmt_file = gmt_file,
extra_sets = extra_sets,
gs_string = gs_string,
padjCutoff = padjCutoff
)
report_template <- system.file("rmarkdown", "templates", "report", "skeleton", "skeleton.Rmd", package = "myReportPkg")
rmarkdown::render(
input_file = report_template,
output_file = output_file,
params = params,
...
)
}
Also by storing the report in the package, you get rmarkdown templates for free, but you can still point users to ?render_result_report for information about the expected variables.
And this is just one package-ized option, there are lot of other structures that could be helpful in this scenario.
p.s. Oh and generate_results.R could be a function, too! 