Citing articles using roxygen2

Question

As in this question, I would like to include citations to articles in function documentation. I use roxygen2 for all documentation, and it appears that there was a pull request to roxygen2 with the necessary functionality, but Hadley turned it down since roxygen2 was in maintenance mode. Have things changed since then? Is there another way to cite/ include article references stored in BibTeX format?

Answer 1

The Rdpack package promises to deliver the functionality that you requested.

To get set up, you also need to add the line RdMacros: Rdpack to your package's DESCRIPTION file (note the capital M), and add Rdpack to the Imports: field.

Then you can save your bibtex library in to inst/REFERENCES.bib, and cite them in your documentation with:

#' @references{
#'   \insertRef{bibtexKey}{YourPackageName}
#' }
#'
#' # The below line ought to be included in at least one of your documentation
#' # sections, so that roxygen2 adds Rdpack to your NAMESPACE file.
#'
#' @importFrom Rdpack reprompt

I initially encountered some errors when first using the package; re-starting R seemed to do the trick.

Warnings about unknown macro '\insertRef' will be encountered if building documentation with devtools::document(), as devtools does not read the 'RdMacros' line of the DESCRIPTION file; they can be safely ignored. The references may not be rendered correctly by devtools, but will be when the package is finally built; to view them in their proper formatting in the interim you can run R CMD Rd2pdf from a separate command window.

Answer 2

Nicely summarized by ms609. I would add that the releases of Rdpack in 2018 provided also macros for citation and the ability to produce the bibliography with a single command insertAllCited{}. Vignette Inserting_bibtex_references, linked also by ms609, provides up-to-date information.

Rdpack::viewRd() can be used to view the rendered citations without building the package, something like:

Rdpack::viewRd("./man/filename.Rd")  # text
Rdpack::viewRd("./man/filename.Rd", type = "html") # html

This may be particularly useful for roxygen2 users since roxygen2 processes the Rd files but doesn't render the references. Just don't forget to update the documentation using devtools::document() or another suitable command before invoking Rdpack::viewRd().