Convert Rd to roxygen documentation and utilities to enhance documentation and building packages
Description
This package contains functions to convert Rd to roxygen documentation. It
can parse an Rd file to a list (parse_file ), create the roxygen
documentation (create_roxygen ) and update the original R script
(e.g. the one containing the definition of the function) accordingly
(Rd2roxygen ). This package also provides utilities which can
help developers build packages using roxygen more easily (rab ).
Note
There is no guarantee to generate perfect roxygen comments that can be converted back to the original Rd files. Usually manual manipulations on the roxygen comments are required. For example, currently '@S3method' is not included in the comments, and '@rdname' is not supported either (users have to move the roxygen comments around and add the appropriate tags by themselves). Patches (as pull requests) are welcome through GitHub: https://github.com/yihui/Rd2roxygen/.
This package is not thoroughly tested, so it is likely that it fails to convert certain parts of Rd files to roxygen comments. As mentioned before, you have to manually deal with these problems. You are welcome to report other serious issues via https://github.com/yihui/Rd2roxygen/issues.
Author(s)
Hadley Wickham and Yihui Xie
See Also
Useful links:
Examples
## see the package vignette: vignette('Rd2roxygen')
Convert all the Rd files of a package to roxygen comments
Description
This function takes a package root directory, parses all its Rd files under the man directory and update the corresponding R source code by inserting roxygen documentation in to the R scripts.
Usage
Rd2roxygen(pkg, nomatch, usage = FALSE)
Arguments
pkg
the root directory of the package
nomatch
the file name (base name only) to use when an object in the Rd file is not found in any R source files (typically this happens to the data documentation); if not specified, the default will be ‘pkg’-package.R
usage
logical: whether to include the usage section in the output
Value
NULL (but the process of conversion will be printed on screen)
Note
ESS users may use options(roxygen.comment = "##' ") to ensure
the generated roxygen comments begin with "##' ", which is the
default setting in Emacs/ESS.
Re-run this function on a package will remove the previous roxygen comments before functions in R scripts.
Author(s)
Yihui Xie <http://yihui.org>
Examples
## a demo package
pkg = system.file("examples", "pkgDemo", package = "Rd2roxygen")
file.copy(pkg, tempdir(), recursive = TRUE) # copy to temp dir first
od = setwd(tempdir())
## take a look at original R scripts
file.show("pkgDemo/R/foo.R")
options(roxygen.comment = "##' ")
## convert Rd's under man to roxygen comments
Rd2roxygen(file.path(tempdir(), "pkgDemo"))
file.show("pkgDemo/R/foo.R") # what happened to foo.R and bar.R?
setwd(od) # restore working directory
Create the roxygen documentation
Description
The parsed information is converted to a vector of roxygen tags.
Usage
create_roxygen(info, usage = FALSE)
Arguments
info
the named list of the parsed documentation
usage
logical: whether to include the usage section in the output (this can be useful when there are multiple functions in a single usage section, but generally it is not necessary because roxygen can generate the usage section automatically)
Value
a character vector
Author(s)
Hadley Wickham; modified by Yihui Xie <http://yihui.org>
Examples
rd.file = system.file("examples", "parse_and_save.Rd", package = "Rd2roxygen")
options(roxygen.comment = "##' ")
create_roxygen(parse_file(rd.file))
Parse the input Rd file and save the roxygen documentation into a file
Description
Parse the input Rd file and save the roxygen documentation into a file
Usage
parse_and_save(path, file, usage = FALSE)
Arguments
path
the path of the Rd file
file
the path to save the roxygen documentation
usage
logical: whether to include the usage section in the output
Value
a character vector if file is not specified, or write the
vector into a file
Author(s)
Hadley Wickham; modified by Yihui Xie <http://yihui.org>
Parse the input Rd file to a list
Description
This function uses the function parse_Rd in the tools package to
parse the Rd file.
Usage
parse_file(path)
Arguments
path
the path of the Rd file
Value
a named list containing the documentation sections as strings
Author(s)
Hadley Wickham; modified by Yihui Xie <https://yihui.org>
Examples
rd.file = system.file("examples", "parse_and_save.Rd", package = "Rd2roxygen")
parse_file(rd.file)
Format the code in the usage and examples sections
Description
The function tidy_source in the formatR package
is used to polish the Rd files generated by roxygen2 in the usage and
examples sections.
Usage
reformat_code(path, ...)
Arguments
path
the path of the Rd file
...
other arguments passed to tidy_source
Value
NULL; as a side effect, the original Rd file will be updated
Note
If the usage or examples code is not syntactically correct, it will not
be reformatted and a message will be printed on screen. One possible
situation is the percent symbol %, which should be escaped even in
the examples code (cf Writing R Extensions), and this can make the code
syntactically incorrect, e.g. a %in% b should be a
\%in\% b but the latter is not valid R code. Anyway, this function
will try to unescape the percent symbols before reformating the code, then
escape them.
Author(s)
Yihui Xie <http://yihui.org>
See Also
Examples
rd.file = system.file("examples", "reformat_code_demo.Rd", package = "Rd2roxygen")
file.copy(rd.file, tempdir())
fmt.file = file.path(tempdir(), "reformat_code_demo.Rd")
file.show(fmt.file) ## show the raw Rd
reformat_code(fmt.file)
file.show(fmt.file) ## the formatted Rd
Roxygenize a package, clean up and build/check the package
Description
After the source package is roxygenized, this function will build the
package. Optionally it also installs or checks the package, reformats the
code in the example sections. Note rab is an alias of
roxygen_and_build .
Usage
roxygen_and_build(
pkg,
build = TRUE,
build.opts = "--no-manual",
install = FALSE,
install.opts = if (build) "" else "--with-keep.source",
check = FALSE,
check.opts = "--as-cran --no-manual",
remove.check = TRUE,
reformat = TRUE,
before = NULL,
...
)
rab(
pkg,
build = TRUE,
build.opts = "--no-manual",
install = FALSE,
install.opts = if (build) "" else "--with-keep.source",
check = FALSE,
check.opts = "--as-cran --no-manual",
remove.check = TRUE,
reformat = TRUE,
before = NULL,
...
)
Arguments
pkg
the root directory of the source package
build
whether to build the package
build.opts
options to be passed to R CMD build
install
whether to install the package
install.opts
options to be passed to R CMD INSTALL
check
whether to check the package
check.opts
options to check the package (e.g. "--no-examples")
remove.check
whether to remove the directory generated by R
CMD check
reformat
whether to reformat the example code; see
reformat_code
before
an R expression to be evaluated under the package root directory before the package is roxygenized and built
...
other arguments passed to roxygenize
Value
NULL
Author(s)
Yihui Xie <http://yihui.org>
Examples
## Not run:
roxygen_and_build("Rd2roxygen", install = TRUE)
## or simply
rab("Rd2roxygen", install = TRUE)
## End(Not run)