R/documentation.R

In Ironholds/practice: Tools for identifying whether R packages follow common software engineering conventions

#'@title identify the presence and source of package
#'vignettes.
#'@description identify how a package's vignettes are built, if it has
#'vignettes.
#'
#'@param package_directory the directory the package
#'source code lives in, returned from \code{\link{get_package_source}}
#'
#' @details There are two things to look for in terms of vignettes: the format,
#' either LaTeX or R markdown, and the vignette builder, typically
#' Sweave or knitr. All .Rmd files are knitr, but .Rnw can be compiled by
#' either.
#' 
#' \code{check_vignettes} looks for a \code{vignettes}
#' folder to see whether .Rnw (LaTeX) files or .Rmd (markdown) files are
#' found. It also checks for a VignetteBuilder option in the DESCRIPTION.
#' 
#' @return A list with two components:
#'   \item{Format}{"None" if no vignettes are found, "LaTeX" if
#' LaTeX .Rnw files are found, "Markdown" if .Rmd files are found.}
#'   \item{Builder}{The package used to compile the vignettes,
#' typically Sweave or knitr.}
#'
#'@examples
#'\dontrun{
#'#Identify how urltools vignettes are built, if it has any.
#'#It does, and if you run this code, you'll see the answer is
#'#"Knitr".
#'file_location <- get_package_source("urltools")
#'check_vignettes(file_location)
#'
#'#Fortunes uses sweave
#'file_location <- get_package_source("fortunes")
#'check_vignettes(file_location)
#'
#'#A3 has no vignettes
#'file_location <- get_package_source("A3")
#'check_vignettes(file_location)
#'}
#'
#'@seealso
#'\code{\link{check_roxygen}} to identify if a package's documentation is
#'formatted using roxygen2, \code{\link{check_changelog}} to see if there
#'is something that looks like a changelog, and the package index for more
#'tests and checks.
#'
#'@export
check_vignettes <- function(package_directory) {
  vignettes <- list(Format = "None", Builder = "None")
  files <- list.files(file.path(package_directory, "vignettes"))
  if (length(files) == 0) {
    return(vignettes)
  }
  
  formats <- c()

  types <- c("LaTeX", "Markdown", "rsp", "rst")
  patterns <- c("\\.Rnw$", ".Rmd$", "(.rsp|.asis)$", "rst$")
  
  types <- types[sapply(patterns, function(p) {
    any(grepl(p, files, ignore.case = TRUE))
    })]
  if (length(types) > 0) {
    vignettes$Format <- paste(types, collapse = "/")
  }
  
  if (vignettes$Format != "None") {
    vignettes$Builder <- "Sweave"  # default
  }
  
  # check vignette builder
  desc_file <- file.path(package_directory, "DESCRIPTION")
  if (file.exists(desc_file)) {
    description <- as.list(read.dcf(desc_file)[1, ])
    names(description) <- tolower(names(description))
    if (!is.null(description$vignettebuilder)) {
      vignettes$Builder <- description$vignettebuilder
    }
  }

  vignettes
}

#'@title check whether a package's documentation uses roxygen2
#'@description identifies if a package's documentation uses
#'roxygen2's inline documentation, by scanning the R files
#'hunting for roxygen2 tags.
#'
#'@param package_directory the full path to the directory, retrieved
#'with \code{\link{get_package_source}}.
#'
#'@details checking for roxygen2 is fairly simple. One way is to
#'look at the ./man files and search for the "% Generated by roxygen2"
#'tag, but early versions of roxygen2 didn't introduce that tag.
#'Instead, we scan the .R files hunting for actual tags, specifically
#'searching for @@export (which every package, presumably, must have
#'at least once - there wouldn't actually be any R it provides if
#'not.)
#'
#'@return either TRUE or FALSE, depending on whether or not
#'roxygen2 tags are found in the source code.
#'
#'@examples
#'\dontrun{
#'#Identify if ggplot2 uses roxygen
#'file_location <- get_package_source("ggplot2")
#'check_roxygen(file_location)
#'remove_package_source(file_location)
#'}
#'
#'@seealso
#'\code{\link{check_vignettes}} to identify if a package has vignettes
#'and how they are built, \code{\link{check_changelog}} to see if there
#'is something that looks like a changelog, and the package index for more
#'tests and checks.
#'
#'@export
check_roxygen <- function(package_directory){
  check_content(file.path(package_directory, "R"), "@export")
}

#'@title identify if the package contains a changelog
#'@description searches through the downloaded source code
#'of a package trying to identify if it has something that
#'looks like a log of changes between versions.
#'
#'@param package_directory the directory the package
#'source code lives in, returned from \code{\link{get_package_source}}.
#'
#'@details changelogs - logs of what changes in a package
#'between versions, be that bug fixes, new features or alterations
#'to how existing features function - are common to R packages
#'and collections of code generally.
#'
#'With R packages, they are normally stored as "NEWS"
#'or "CHANGELOG" files. \code{check_changelog} checks
#'for the presence of a changelog by seeing if there are any files
#'in the root directory of the package source code that match
#'the case-insensitive regular expression "(change|news)".
#'
#'@return TRUE if the package has something that looks
#'like a changelog, FALSE otherwise.
#'
#'@examples
#'\dontrun{
#'#Does A3 have a changelog? (yes)
#'file_location <- get_package_source("A3")
#'result <- check_changelog(file_location)
#'
#'#What about "fortunes"? (no)
#'file_location <- get_package_source("fortunes")
#'result <- check_changelog(file_location)
#'}
#'
#'@seealso
#'\code{\link{check_vignettes}} to identify if a package has vignettes
#'and how they are built, \code{\link{check_roxygen}} to see if inline
#'documentation is built with roxygen2, and the package index for more
#'tests and checks.
#'
#'@export
check_changelog <- function(package_directory){
  files <- list.files(package_directory, pattern = "(change|news)", ignore.case = TRUE)
  if(length(files)){
    return(TRUE)
  }
  return(FALSE)
}