knitr::opts_chunk$set(comment = NA, message = FALSE) options(formatR.blank = FALSE, width = 60)
The package Rd2roxygen helps R package developers who used to write R documentation in the raw LaTeX-like commands but now want to switch their documentation to roxygen2, which is a convenient tool for developers, since we can write documentation as inline comments, e.g.
## the source code of the function `parse_and_save` ex.file = system.file('examples', 'parse_and_save.R', package = 'Rd2roxygen') cat(readLines(ex.file), sep = '\n')
With roxygen2 (typically using roxygenize()
), we can create the real
Rd file from the above source code like this:
rd.file = system.file('examples', 'parse_and_save.Rd', package = 'Rd2roxygen') cat(readLines(rd.file), sep = '\n')
The Rd2roxygen package goes exactly in the opposite way -- it parses the Rd files and turns them back to roxygen comments. We can either do this job on single Rd files, or just convert the whole package. The latter might be more useful for developers who are considering the transition from Rd to roxygen.
The function Rd2roxygen::Rd2roxygen()
can take a path of a source package, parse all
the Rd files under the man
directory, and write the roxygen comments right
above the source code of the functions under the R
directory. See
?Rd2roxygen
for an example.
Rd2roxygen::Rd2roxygen('path/to/source/pkg') ## there must be 'man' and 'R' directories under this path
Note the path to the package should not be .
. You are recommended to call this function in the directory that contains the source package.
We can parse a single Rd file and create the roxygen comments as well with
parse_file()
and create_roxygen()
, e.g.
library(Rd2roxygen) ## we can specify the roxygen comments prefix (#' by default) options(roxygen.comment = "##' ") str(info <- parse_file(rd.file)) # parse_and_save() combines these two steps cat(create_roxygen(info), sep = '\n')
This package also provides a tool roxygen_and_build()
(or in short rab()
)
to help us build the package.
The main feature of rab()
is the option to "reformat" the code in the
usage and example sections. If we specify reformat = TRUE
in rab()
, the
code will be reformated like this:
## original code rab=function(pkg,build=TRUE,install=FALSE, check=FALSE,check.opts='',remove.check=TRUE,reformat=TRUE,...){}
## the reformatted code; note the spaces and indent rab=function(pkg,build=TRUE,install=FALSE, check=FALSE,check.opts='',remove.check=TRUE,reformat=TRUE,...){}
Note this functionality depends on the package formatR, and
sometimes it might not be possible to reformat the code, e.g. the
\dontrun{}
command in Rd can contain arbitrary texts, which means there
could be illegal R expressions and formatR will be unable to format the
code. In this case, the original code will not be reformatted and a message
will be printed on screen.
This vignette was built using the vignette engine knitr::rmarkdown
in the knitr package. You can find the source
in the Rd2roxygen
repository on
Github, or
system.file('doc', 'Rd2roxygen.Rmd', package='Rd2roxygen')
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.