I'm aware of this documentation (https://cran.r-project.org/web/packages/roxygen2/vignettes/extending.html) but I am struggling to make it work for a custom "home brew" package. All I really need is a "simple" custom tag e.g. @information
. There seems to be some information missing to bridge the gap (for me) between the documentation and actually having it work in a package (a working example would be great).
I also found this video:
https://www.youtube.com/watch?v=AcibRDNSfoM
and related repositories:
https://github.com/shahronak47/informationtag
https://github.com/shahronak47/infotagdemo
However, they also don't seem to be doing what I would expect.
Can anyone point me at some useful examples?
Leaning on the example made with the @tip
tag in the Extending roxygen2 vignette for a simple descriptive tag @information
all you need to do is create a file in the R/
folder of your package and add this content to the file:
#' @importFrom roxygen2 roxy_tag_parse
#' @importFrom roxygen2 roxy_tag_rd
NULL
# define a roxy_tag_parse() method that describes how to parse the tag
# text. Here it will be processed using Markdown
#' @export
roxy_tag_parse.roxy_tag_information <- function(x) {
roxygen2::tag_markdown(x)
}
# define a roxy_tag_rd() method that describes how to convert the tag
# into `.Rd` commands
#' @export
roxy_tag_rd.roxy_tag_information <- function(x, base_path, env) {
roxygen2::rd_section("information", x$val)
}
# Since we provided our own type "information" in rd_section() we need
# to define a format method for this type
# Feel free to adapt this method to your needs
#' @export
format.rd_section_information <- function(x, ...) {
paste0(
"\\section{Information}{\n",
"\\itemize{\n",
paste0(" \\item ", x$value, "\n", collapse = ""),
"}\n",
"}\n"
)
}
Later on you can just use the tag as any other tag in your roxygen headers:
#' @information This is some important information I want to display!
Hope this helps!
EDIT:
If you want to create a separate package for custom roclets and import them when needed, then in your custom package {myroclets}
create a file in R/
and add the same contents as stated above. Additionally you need to add a constructor for your @information
tag so append the file with
#' @export
information_roclet <- function() {
roxygen2::roclet("information")
}
to export your information_roclet
.
In the case you need to use the information_roclet
in another package of yours, just add to DESCRIPTION
Roxygen: list(roclets = c("collate",
"rd",
"namespace",
"myroclets::information_roclet"),
packages = "myroclets")
where myroclets
is the package where the information_roclet
was originally created.