Search code examples
rdocumentationroxygen2

R package documentation: link to a whole package, not function

I want to cite another package (the whole package, not just a function from it) in the documentation of some functions I'm developing. I am using Roxygen2 comments to document my package functions.

I cannot find a way to create a link to a whole third-party package using Roxygen2. To link to a package function, one would write [pkg::fun()] but I don't know how to create a link to the package itself.

Some packages expose a general man page, and it's possible to link to it via e.g. [pkg::pkg].

But many packages don't have this and there's just a general package vignette with the list of functions and a link to the description: enter image description here

Such page can be reached by clicking on a package name in the packages tab in RStudio.

How can I link to it from a function documentation made in Roxygen2 markdown.?

Solution

  • Coming back to this ... My original answer seems to be partly wrong.

    The manual does mention a possibility, which is (since R 3.2.0) the built-in macro \packageIndices. If you want to link to the index of a package named baz, then you can ask maintainer("baz") to do the following. Create a file man/baz-index.Rd containing

    \name{baz-index}
\alias{baz-index}
\title{Index of Package \pkg{baz}}
\description{\packageIndices{baz}}

    then build and install baz twice to bootstrap the index. (The first stage generates the Rd objects that are used in the second stage to populate the index.) After the second install, help("baz-index", package = "baz") and ?baz::`baz-index` will render the index.

    The second tarball can be submitted to CRAN (or whatever repository), allowing other packages with at least Enhances: baz to link to the index in their help pages with \link[baz]{baz-index} or \link[baz:baz-index]{<text>}.

    FWIW, I said that my original answer was partly wrong rather than entirely wrong because the built-in macro \packageIndices gives you an index without hyperlinks. If you want hyperlinks, then you may need to hack, i.e., define your own macro calling a hacked version of tools:::Rd_package_indices. Not worth the effort for one package, IMO, but could be an interesting proposal for tools ...