Add new packgaes meta field (#1059)

Fixes #1013

NEWS.md

@@ -31,6 +31,15 @@
 * Empty annotations (alternate text) for figures added via markdown are now
   omitted. This caused issues when generating pkgdown web sites (#1051).
 
+* Roxygen metadata can now have a `packages` element, giving a character vector 
+  of package names to load. This makes it easier to use extension package that 
+  provide new tags for existing roclets (#1013). See `?load_options` for
+  more details.
+
+    ```yaml
+    Roxygen: list(markdown = TRUE, packages = "roxygenlabs")
+    ```
+
 * `@evalNamespace()` works again (#1022).
 
 * `@description NULL` and `@details NULL` no longer fail; instead, these tags 

R/options.R

@@ -1,12 +1,46 @@
 #' Load roxygen2 options
 #'
+#' @description
 #' Options can be stored in the `Roxygen` field of the `DESCRIPTION`, or
 #' in `man/roxygen/meta.R`. In either case, the code is parsed and evaluated
 #' in a child of the base environment. Call `roxy_meta_get()` to access
 #' current option values from within tag and roclet methods.
 #'
 #' Options in `man/roxygen/meta.R` override those present in `DESCRIPTION`.
 #'
+#' @section Possible options:
+#'
+#' * `roclets` `<character>`: giving names of roclets to run. See
+#'    [roclet_find()] for details.
+#'
+#' * `packages` `<character>`: packages to load that implement new tags.
+#'
+#' * `load` `<string>`: how to load R code. See [load] for details.
+#'
+#' * `old_usage` `<flag>`: use old style usage formatting?
+#'
+#' * `markdown` `<flag>`: translate markdown syntax to Rd?
+#'
+#' * `r6` `<flag>`: document R6 classes?
+#'
+#' * `current_package` `<string>` (read only): name of package being documented.
+#'
+#' @section How to set:
+#' Either set in `DESCRIPTION`:
+#'
+#' ```
+#' Roxygen: list(markdown = TRUE, load = "installed")
+#' ```
+#'
+#' Or if longer, you can put in `/man/roxygen/meta.R`:
+#'
+#' ```
+#' list(
+#'   markdown = TRUE,
+#'   load = "installed"
+#' )
+#' ```
+#'
 #' @param base_path Path to package.
 #' @export
 #' @keywords internal
@@ -17,11 +51,12 @@ load_options <- function(base_path = ".") {
 
   defaults <- list(
     roclets = c("collate", "namespace", "rd"),
+    packages = character(),
     load = "pkgload",
     old_usage = FALSE,
     markdown = FALSE,
     r6 = TRUE,
-    package = NA_character_
+    current_package = NA_character_
   )
 
   unknown_opts <- setdiff(names(opts), names(defaults))
@@ -46,7 +81,7 @@ load_options_description <- function(base_path = ".") {
     opts <- eval(parse(text = desc_opts), child_env(baseenv()))
   }
 
-  opts$package <- dcf[[1, 2]]
+  opts$current_package <- dcf[[1, 2]]
   opts
 }
 

R/roxygenize.R

@@ -40,6 +40,10 @@ roxygenize <- function(package.dir = ".",
 
   roxy_meta_load(base_path)
 
+  # Load required packages for method registration
+  packages <- roxy_meta_get("packages")
+  lapply(packages, requireNamespace, quietly = TRUE)
+
   roclets <- roclets %||% roxy_meta_get("roclets")
   # Special case collate: it doesn't need to execute code, and must be run
   # first to ensure that code can be executed