link to package vignette

[danielsjf]

At the moment it is possible to link to package functions, but not to the vignettes.
\code{\link{function}}
source: https://cran.r-project.org/web/packages/roxygen2/vignettes/formatting.html

Would it be possible to implement direct links to vignettes too in the future? Example code:
\link{vignette_name}

Closest work-around: https://stackoverflow.com/questions/22649124/reference-package-vignettes-with-roxygen2

[tbates]

@gaborcsardi mentions browseVignettes("roxygen2") in the roxygen vignette about markdown

vignettes/markdown

[danielsjf]

Yeah, that's a way to list the vignettes, but is also not a direct link to the vignette from the documentation in the way that the links to the function work.

[gaborcsardi]

TBH I am not sure what this issue is about. Does Rd markup support linking to vignettes at all?

[hadley]

Unfortunately roxygen2 can't link to vignettes because R itself provides no way to link to vignettes from Rd files.

[dmurdoch]

R does provide a way to link from Rd files to vignettes, and has since I added Rd user macros to the help system many years ago. This macro:

https://github.com/dmurdoch/rgl/blob/d81b3686e00f2571f5a0e44200cc1ea90e723387/man/macros/macros.Rd#L10-L17

will generate a link to an HTML vignette from an Rd file. If you use PDF vignettes, it would just need a small modification.

By default it is set up to work with dynamic help in R or RStudio. To use it in pkgdown, set the environment variable RdVignettePath to the relative path to the vignettes directory, e.g. in the Github action producing the site:

https://github.com/dmurdoch/rgl/blob/d81b3686e00f2571f5a0e44200cc1ea90e723387/.github/workflows/pkgdown.yaml#L25

For other static help systems, use the appropriate path in this env var.

Linking to a vignette in a different package needs a different URL pattern; the macros.Rd file contains one to link to the CRAN copy of a vignette.