R/documenttools.R

In charlotte-ngs/rcoursetools: R Course Tools

###
###
###
###   Purpose:   Collection of tools for documents
###   started:   2016/02/03 (pvr)
###
### ################################################ ###

#' Create a course website
#'
#' @param psCourseName   Name of the course
#' @param psCourseDir    Course directory
#' @param psWsTemplate   Website template
#' @export create_course_website
create_course_website <- function(psCourseName, psCourseDir = ".", psWsTemplate = NULL){
  ### # specify the course package directory
  sCoursePackDir <- file.path(psCourseDir, psCourseName)
  ### # check that course package exists
  stopifnot(dir.exists(sCoursePackDir))
  ### # if template is not specified use a template from rmarkdown
  if (is.null(psWsTemplate)) {
    devtools::use_vignette(name = "index", pkg = sCoursePackDir)
  } else {
    sWsTemplate <- psWsTemplate
    file.copy(from = sWsTemplate, to = file.path(sCoursePackDir, "vignettes", "index.Rmd"), recursive = TRUE)
  }
  invisible(TRUE)
}


#' Create a course document
#'
#' @description
#' \code{create_course_document} assumes that psPkgPath is a
#' directory that contains an R-package. By default the new
#' document is created in subdirectory "vignettes". If this
#' subdirectory does not exist, it is created. The document
#' is generated by the function \code{rmarkdown::draft} using
#' the template "pdf_document".
#'
#' @details
#' The basic functionality follows the function
#' \code{devtools::use_vignette}, except for the possibility
#' of specifying any given template from any package. The template
#' can be specified via argument "psRmdTemplate". This requires
#' in the package given by psTemplatePkg that a subdirectory with
#' the name of the template exists under "rmarkdown/templates".
#' More information about setting up custom templates is obtained
#' in the helpfile of rmarkdown::draft.
#'
#' @param   psDocuName       name of the new document
#' @param   psPkgPath        path where package is located under which document should be created
#' @param   psRmdTemplate    name of the template to be used
#' @param   psTemplatePkg    package from where the template should be taken
#' @param   psDocuSubdir     subdirectory in which document should be saved to
#' @param   pbCreateSubdir   should new document be put in a separate subdirectory
#' @param   pbEdit           directly open newly created document
#' @export create_course_document
create_course_document <- function(psDocuName,
                                   psPkgPath      = ".",
                                   psRmdTemplate  = "pdf_document",
                                   psTemplatePkg  = "rcoursetools",
                                   psDocuSubdir   = "vignettes",
                                   pbCreateSubdir = TRUE,
                                   pbEdit         = TRUE) {
  ### # do the preparation similar to devtools::use_vignette
  pkg <- devtools::as.package(psPkgPath)
  devtools:::check_suggested("rmarkdown")
  devtools:::add_desc_package(pkg, "Suggests", "knitr")
  devtools:::add_desc_package(pkg, "Suggests", "rmarkdown")
  devtools:::add_desc_package(pkg, "VignetteBuilder", "knitr")
  if (pbCreateSubdir){
    sDocuSubdir <- file.path(pkg$path, psDocuSubdir, psDocuName)
  } else {
    sDocuSubdir <- file.path(pkg$path, psDocuSubdir)
  }
  dir.create(sDocuSubdir, showWarnings = FALSE, recursive = TRUE)
  sDocuPath <- file.path(sDocuSubdir, paste0(psDocuName, ".Rmd"))
  rmarkdown::draft(file = sDocuPath,
                   template = psRmdTemplate,
                   package = psTemplatePkg,
                   create_dir = FALSE,
                   edit = FALSE)
  if (pbEdit) file.edit(sDocuPath)
  message("Draft vignette created in ", sDocuPath)
}


#' Create a document from a template
#'
#' @description
#' The function \code{create_rmd_document} copies a template document
#' from any given package to the path that is specified using
#' the name that is given with parameter \code{psDocuName}.
#'
#' @details
#' The format of the created document is assumed to be Rmarkdown.
#' The extension .Rmd will be added to the given document name.
#' This function does not make any assumption about the environment
#' in which the new document is created. Hence this function can
#' be used outside of R-Packages or RStudio-projects.
#'
#' @param   psDocuName           name of the new document without extension
#' @param   psDocuPath           path where document should be created
#' @param   psRmdTemplate        name of the template to be used
#' @param   psTemplatePkg        package from where the template should be taken
#' @param   pbCreateDocuSubdir   separate subdirectory for document psDocuName
#' @param   pbEdit               directly open newly created document
#' @export  create_rmd_document
create_rmd_document <- function(psDocuName,
                            psDocuPath         =  ".",
                            psRmdTemplate       =  "pdf_document",
                            psTemplatePkg       =  "rcoursetools",
                            pbCreateDocuSubdir  =  TRUE,
                            pbEdit              =  TRUE) {
  ### # initialize the document path to the function parameter psDocuPath
  sDocuPath <- psDocuPath
  ### # in case a separate subdirectory for the document is required, add
  ### #  document name to the document path
  if (pbCreateDocuSubdir)
    sDocuPath <- file.path(sDocuPath, psDocuName)
  ### # in case the document path does not exist, create it
  if (!dir.exists(sDocuPath))
    dir.create(sDocuPath, showWarnings = FALSE, recursive = TRUE)
  ### # set the document name including the path
  sDocuName <- file.path(sDocuPath, paste(psDocuName, "Rmd", sep = "."))
  rmarkdown::draft(file = sDocuName,
                   template = psRmdTemplate,
                   package = psTemplatePkg,
                   create_dir = FALSE,
                   edit = FALSE)
  if (pbEdit) file.edit(sDocuName)
  message("Draft vignette created in ", sDocuName)
}