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

Question

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:

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.?

Championship

where in the documentation are you trying this? the description file? can you provide more detail in what you are trying to accomplish? – Markos

No, in the documentation of one of my package functions. I want to specify in my function documentation that it relies on another package. I'm editing the question. – Championship

Does the other package have a package-level documentation page? Not all do. You can also just use a regular markdown or roxygen link to link to whatever you think is the best reference for the other package r-pkgs.org/man.html?q=link#links – Giannini

They have, but I don't know how to reference it. How should I name it? – Championship

Without having a place I can test it out, [pkg::pkg] might work. If not, just use a full markdown link, e.g. [roxygen2](https://roxygen2.r-lib.org/) – Giannini

The [pkg::pkg] solution works well for packages having general documentation page with its own man page, like rentrez. Other packages don't have this but still RStudio can show the general vignette if you click on the package name, so it should be linkable I guess. See for example crrri. – Championship

That's not a vignette though, that's just the list of exports. I'm not sure how that gets generated exactly, but it's automatic. Maybe just link to whatever functions / vignettes / etc seem most relevant, because if the package maintainer hasn't made package-level documentation, I don't know what else you could really reference – Giannini

Answer 1

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

Thermoplastic

Answer 2

You cannot link to the page that comes up when you click on the name of a package in RStudio's Packages pane. RStudio invisibly calls help(package = "<name>"), which renders the package's index.

From the R-exts manual:

The markup \link{foo} (usually in the combination \code{\link{foo}}) produces a hyperlink to the help for foo. Here foo is a topic, that is the argument of \alias markup in another Rd file (possibly in another package).

Hence \link and the equivalent Markdown markup supported by roxygen2 can only link to topics. A package index is not a topic in this sense because there is no corresponding Rd file.

It might be best just to remind users that they can use help to access the index of the package to which you are referring.

Thermoplastic

that's a pity... Also because it appears in the Help tab of RStudio, so in theory it could be implemented someway – Championship