Experimental ‘roxygen’ Tags and Extensions
Experimental ‘roxygen’ Tags and Extensions
Once on CRAN, install the package with
install.packages("roxygenlabs")x
Currently there is no official way to load a package when running
devtools::document()
or roxygen2::roxygenize()
, but you can use a
trick: put the package loading code into the Roxygen
field in
DESCRIPTION
:
Roxygen: { library(roxygenlabs); list(markdown = TRUE) }
The @examplesIf
tag implements conditional examples, that do not run
when running example()
and R CMD check
, unless some condition holds.
You can use this mechanism to avoid running some examples on CRAN and/or
during R CMD check
, without adding boilerplate code to the examples
themselves. The following example only runs if the computer is online:
#' @examplesIf curl::has_internet()
#' curl::curl_fetch_memory("https://httpbin.org/status/200")
If you never want to run an example, use FALSE
as the condition. This
makes sense for examples that take a very long time to run:
#' @examplesIf FALSE
#' some very long running computation...
To support @examplesIf
in R6 classes you need to use the
roxygenlabs_rd
roclet. E.g. add this to DESCRIPTION
:
Roxygen: { library(roxygenlabs); list(markdown = TRUE,
roclets = c("collate", "namespace", "roxygenlabs_rd")) }
The @theme
tag allows adding CSS and JS files to the HTML version of
the manual pages.
To support @theme
, you need to use the roxygenlabs_rd
roclet. E.g.
add this to DESCRIPTION
:
Roxygen: { library(roxygenlabs); list(markdown = TRUE,
roclets = c("collate", "namespace", "roxygenlabs_rd")) }
and then use the @theme
tag to add CSS/JS files to all manual pages.
Multiple file names can be specicified in a single @theme
tag, and
file names are relative to the inst/doc
directory, within the package:
#' @theme assets/extra.css assets/rd.js
See the assets/extra.css
and assets/rd.js
files, included in the
package, for an example CSS/JS theme that has the following changes
compared to plain Rd documentation:
- R code is syntax-highlighted. This includes R code in the “Usage”
and “Examples” sections, R code created via “r” fences in roxygen’s
markdown, and R code chunks produced by roxygen’s
@includeRmd
tag. - Add a “Copy” button to R code chunks, to copy them to the clipboard.
- Headings have a new style, including a serif font.
- More spacious formatting of arguments and list.
- Restrict the width of the manual page, to avoid very long lines.
MIT © RStudio