3 Package setup

We start by specifying the information needed in the DESCRIPTION file of the R package. We mostly follow the R Packages book’s description of version numbering. Releases 0.0.1, 0.0.2, and 0.0.3 should really have been 0.1.0, 0.2.0, and 0.3.0, because these were not just patches. Rather, each added quite substantial new functionality. For this reason, we have gone straight from 0.0.3 to 0.4.0. We will keep the leftmost number (“major release”) at 0 until we feel like the package is complete with all the intended features.

usethis::create_package(
  path = ".",
  fields = list(
    Package = params$package_name,
    Version = "0.9.2",
    Title = "Literate Programming for Writing R Packages",
    Description = "Allows one to fully create an R package in a single .Rmd 
    file.  Includes functionality and .Rmd templates for a literate programming
    approach to R package development.",
    `Authors@R` = c(
      person("Jacob", "Bien", email = "jbien@usc.edu", role = c("aut", "cre")),
      person("Patrick Vossler", role = "aut")
      )
   )
 )

usethis::use_mit_license(copyright_holder = "J. Bien")

Let’s add some package-level documentation. This is what will show up when someone types package?litr in the console.

#' Literate Programming for Writing R Packages
#'
#' Allows one to fully create an R package in a single .Rmd file.  Includes
#' functionality and .Rmd templates for a literate programming approach to R
#' package development.
#' 
#' @examples
#' \dontrun{
#' # Make a file create-rhello.Rmd based on a template
#' litr::draft("rhello")
#' # Now call litr::render (or press Knit if in RStudio) to generate not just
#' # create-rhello.html, but also an R package called `rhello`.
#' litr::render("create-rhello.Rmd")
#' }
#' @docType package
#' @seealso \code{\link{render}}

3.1 A note on circularity

Keeping track of the version of litr used is particularly important when using litr to develop litr. There is a tendency to want to use the new functionality that we are creating in create-litr.Rmd itself as soon as we have defined it. However, this is circular and thus must be avoided. To see why we need to be careful, let’s consider an actual example that arose when working on litr version 0.0.3. After release v0.0.2, one of the new features we added is a new language engine called package_doc that allows us to have a special kind of code block defining the package documentation. In trying out this feature and making sure it works on skeleton.Rmd, we would most likely install version 0.0.3. Now that version 0.0.3 is installed, there will be a tendency to want to add a package_doc block to create-litr.Rmd, and it will appear to work. However, this is circular, because we have used version 0.0.3 to create version 0.0.3! In particular, if we remove litr and re-install it from github, we will get version 0.0.2 so that when we attempt to create the package using litr::render("create-litr.Rmd"), we will get an error telling us that it doesn’t have a language engine named package_doc.

The code chunk in this section is for preventing this from happening.

For more on circularity, see the section on testing litr.

install_version_of_litr <- utils::packageVersion("litr")
remote <- remotes::github_remote(
  repo = "jacobbien/litr-project@*release",
  subdir = "litr"
  )
version_of_latest_release <- stringr::str_remove(remote$ref, "v")
if (install_version_of_litr != version_of_latest_release)
  stop(stringr::str_glue(
    "You should be using the version of litr from the latest release (version",
    " {version_of_latest_release}),\n but you are using version",
    " {install_version_of_litr}.\n",
    "You can install the release version of litr from GitHub by running the",
    " the following command:\n",
    "remotes::install_github(repo='jacobbien/litr-project@*release', subdir = 'litr')"
  ))