Package 'rdoxygen'

Calls doxygen for an R package

Description

Creates doxygen documentation and optionally wraps it as an R vignette.

Usage

doxy(pkg = ".", doxyfile = "inst/doxygen/Doxyfile", options = c(),
  vignette = FALSE, verbose = TRUE)

Arguments

pkg	A string with the path to any subfolder of the R package root directory. Default: ".".
doxyfile	A string with the path to the Doxyfile relative to the package root folder indicated by pkg. Default: "inst/doxygen/Doxyfile".
options	A named vector with new settings. The names represent the tags. A list of options can be found here: http://www.doxygen.nl/manual/config.html.
vignette	A boolean. Should a vignette be added with doxy_vignette? Default: FALSE.
verbose	Logical. If FALSE, suppresses Doxygen output. Default: TRUE.

Details

This function will first create a Doxyfile with doxy_init if it doesn't yet exist. Next, it runs Doxygen on the Doxyfile, and if vignette = TRUE, creates a vignette allowing the Doxygen documentation to be viewed from within R with a call to vignette(). The Doxygen vignette is created with default options. To modify these options, see doxy_vignette.

Value

NULL

---

Edits an existing Doxyfile

Description

Changes options in doxygen config files.

Usage

doxy_edit(pkg = ".", doxyfile = "inst/doxygen/Doxyfile",
  options = c())

Arguments

pkg	A string with the path to any subfolder of the R package root directory. Default: ".".
doxyfile	A string with the path to the Doxyfile relative to the package root folder indicated by pkg. Default: "inst/doxygen/Doxyfile".
options	A named vector with new settings. The names represent the tags. A list of options can be found here: http://www.doxygen.nl/manual/config.html.

Value

NULL

---

Prepares the R package structure for use with doxygen

Description

Creates a Doxygen configuration file and sets a few options:

• INPUT = src/ inst/include

• OUTPUT_DIRECTORY = inst/doxygen/

• GENERATE_LATEX = NO

• HIDE_UNDOC_MEMBERS = YES

• USE_MATHJAX = YES

• PROJECT_NAME = name_of_R_package

Usage

doxy_init(pkg = ".", doxyfile = "inst/doxygen/Doxyfile",
  verbose = TRUE)

Arguments

pkg	A string with the path to any subfolder of the R package root directory. Default: ".".
doxyfile	A string with the path to the Doxyfile relative to the package root folder indicated by pkg. Default: "inst/doxygen/Doxyfile".
verbose	Logical. If FALSE, suppresses Doxygen output. Default: TRUE.

Details

While the package developer is free to change the OUTPUT_DIRECTORY to wherever they like, the default value above is suggested for compatibility with the devtools package authoring workflow. See doxy_vignette for details.

Value

NULL.

Examples

## Not run: 
doxy_init()

## End(Not run)

---

Creates a doxygen vignette

Description

Creates an R Markdown wrapper for the doxygen documentation, so that it can be viewed from within R with a call to vignette().

Usage

doxy_vignette(pkg = ".", index = "html", viname, vientry)

Arguments

pkg	A string with the path to any subfolder of the R package root directory. Default: ".".
index	A string with the path relative to inst/doxygen of the doxygen index.html file. Default: html (see Note).
viname	A string giving the name of the .Rmd vignette file wrapping the documentation, as well as the name by which to retrieve the documentation using vignette(). Default: "pkgName-Doxygen.Rmd".
vientry	A character string specifying the vignette Index Entry to use. Default: "pkgName C++ library documentation".

Details

This function creates the file vignettes/viname.Rmd in the package root folder, containing the necessary meta-data for viewing the Doxygen HTML documentation from within R with a call to vignette().

Value

NULL

Note

The call to vignette() will *only* open HTML files stored in the doc subfolder of an installed package. Therefore, a natural location for the doxygen documentation (doxydoc) is in inst/doc/doxygen. However, the latest version of devtools incontrovertibly deletes inst/doc during the build/install process. Due to the ubiquitous usage of devtools among R package developers, the doxydoc is stored here in inst/doxygen, and during the build process, moved (or technically, copied and source added to .Rbuildignore) via a vignettes/Makefile. Packages with their own such Makefile will not have it overwritten, and developers may view the default Makefile provided by rdoxygen with the call

cat(readLines(system.file("sys", "Makefile",
                          package = "rdoxygen")), sep = "\n")

---