Devtools :: document vs roxygen2 :: roxygenize
A while ago I read somewhere which is devtools::document
better than roxygen2::roxygenize
for "complex packets / sitations" (which is what I remember) but unfortunately I can't find the link now and I didn 't go deep at that time ...
Looking at the relevant help pages, it is not clear to me how, so my question is if there is ever better use devtools::document
, not
roxygen2::roxygenize
when is this the case? for which packages?
Thanks, Luca
source to share
You are reminiscent of the roxygen2 README :
Roxygen does live code analysis: it downloads all the code in your package, so it can generate documentation using values in the R environment, not just the source code. However, simulating a package download is quite difficult, in general, so there are two ways to do it with roxygen:
roxygen2 :: roxygenise () just exports all files to the R / directory
devtools :: document () prints out all the files in the R / directory, compiles the source code in the src / directory, loads the data into the data / directory, and generally does an accurate simulation of package loading.
If you have a simple package you can use roxygenise (), but for something more complex, I recommend you use document ().
You can see this difference in what document
calls roxygenise
(through devtools:::document_roxygen3
) after doing a lot of other things:
> document
function (pkg = ".", clean = FALSE, roclets = c("collate", "namespace",
"rd"), reload = TRUE)
{
if (!is_installed("roxygen2", 3)) {
stop("Please install latest roxygen2", call. = FALSE)
}
pkg <- as.package(pkg)
message("Updating ", pkg$package, " documentation")
man_path <- file.path(pkg$path, "man")
if (!file.exists(man_path))
dir.create(man_path)
if (clean) {
file.remove(dir(man_path, full.names = TRUE))
}
if (!is_loaded(pkg) || (is_loaded(pkg) && reload)) {
try(load_all(pkg, reset = clean))
}
document_roxygen3(pkg, roclets)
clear_topic_index(pkg)
invisible()
}
<environment: namespace:devtools>
> devtools:::document_roxygen3
function (pkg, roclets)
{
with_envvar(r_env_vars(), with_collate("C", roxygen2::roxygenise(pkg$path,
roclets = roclets, load_code = pkg_env)))
}
<environment: namespace:devtools>
source to share