19

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?

Community
  • 1
  • 1
tchakravarty
  • 10,736
  • 12
  • 72
  • 116
  • Try to put a "CITATION" file under inst folder of your package? For example, https://github.com/cran/GMD/blob/master/inst/CITATION – xb. Jan 28 '15 at 14:10
  • 1
    @xb No, that is the citation for the package, not to cite external articles. – tchakravarty Jan 28 '15 at 14:12
  • Then try to include a .bib file in your .Rnw if you use such type of vignette? For example, `\bibliographystyle{plain} \bibliography{vignette.bib}` – xb. Jan 28 '15 at 14:18
  • @xb Thanks, but again, that is a different use case. I want to be able to use something like the proposed `@cite` tag from the pull request to cite articles as I write inline `roxygen2` function documentation. I am aware that `RMarkdown` allows external bibliographies. – tchakravarty Jan 28 '15 at 14:20

2 Answers2

7

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.

Martin Smith
  • 3,687
  • 1
  • 24
  • 51
5

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().

Georgi Boshnakov
  • 136
  • 1
  • 3
  • Note that you cannot put four spaces or more before \insertAllCited{}! – Denis Cousineau Apr 01 '21 at 19:56
  • Indeed, but only if you have activated markdown for your roxygen2 comments. Note that the example by @mc609 above can be used safely, the trouble occurs only if you have activated markdown and aligned `\insertRef` with the second e of @references. – Georgi Boshnakov Apr 02 '21 at 22:22