Title: | Convert Rd to 'Roxygen' Documentation |
---|---|
Description: | Functions to convert Rd to 'roxygen' documentation. It can parse an Rd file to a list, create the 'roxygen' documentation and update the original R script (e.g. the one containing the definition of the function) accordingly. This package also provides utilities that can help developers build packages using 'roxygen' more easily. The 'formatR' package can be used to reformat the R code in the examples sections so that the code will be more readable. |
Authors: | Hadley Wickham [aut],
Yihui Xie [aut, cre] |
Maintainer: | Yihui Xie <[email protected]> |
License: | GPL |
Version: | 1.16.1 |
Built: | 2024-08-23 05:47:52 UTC |
Source: | https://github.com/yihui/Rd2roxygen |
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
).
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.
Hadley Wickham and Yihui Xie
Useful links:
## see the package vignette: vignette('Rd2roxygen')
## see the package vignette: vignette('Rd2roxygen')
The parsed information is converted to a vector of roxygen tags.
create_roxygen(info, usage = FALSE)
create_roxygen(info, usage = FALSE)
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) |
a character vector
Hadley Wickham; modified by Yihui Xie <http://yihui.org>
rd.file = system.file("examples", "parse_and_save.Rd", package = "Rd2roxygen") options(roxygen.comment = "##' ") create_roxygen(parse_file(rd.file))
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
parse_and_save(path, file, usage = FALSE)
parse_and_save(path, file, usage = FALSE)
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 |
a character vector if file
is not specified, or write the
vector into a file
Hadley Wickham; modified by Yihui Xie <http://yihui.org>
This function uses the function parse_Rd
in the tools package to
parse the Rd file.
parse_file(path)
parse_file(path)
path |
the path of the Rd file |
a named list containing the documentation sections as strings
Hadley Wickham; modified by Yihui Xie <https://yihui.org>
rd.file = system.file("examples", "parse_and_save.Rd", package = "Rd2roxygen") parse_file(rd.file)
rd.file = system.file("examples", "parse_and_save.Rd", package = "Rd2roxygen") parse_file(rd.file)
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.
Rd2roxygen(pkg, nomatch, usage = FALSE)
Rd2roxygen(pkg, nomatch, usage = FALSE)
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 |
NULL (but the process of conversion will be printed on screen)
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.
Yihui Xie <http://yihui.org>
## 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
## 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
The function tidy_source
in the formatR package
is used to polish the Rd files generated by roxygen2 in the usage and
examples sections.
reformat_code(path, ...)
reformat_code(path, ...)
path |
the path of the Rd file |
... |
other arguments passed to |
NULL
; as a side effect, the original Rd file will be updated
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.
Yihui Xie <http://yihui.org>
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
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
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
.
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, ... )
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, ... )
pkg |
the root directory of the source package |
build |
whether to build the package |
build.opts |
options to be passed to |
install |
whether to install the package |
install.opts |
options to be passed to |
check |
whether to check the package |
check.opts |
options to check the package (e.g. |
remove.check |
whether to remove the directory generated by |
reformat |
whether to reformat the example code; see
|
before |
an R expression to be evaluated under the package root directory before the package is roxygenized and built |
... |
other arguments passed to |
NULL
Yihui Xie <http://yihui.org>
## Not run: roxygen_and_build("Rd2roxygen", install = TRUE) ## or simply rab("Rd2roxygen", install = TRUE) ## End(Not run)
## Not run: roxygen_and_build("Rd2roxygen", install = TRUE) ## or simply rab("Rd2roxygen", install = TRUE) ## End(Not run)