I am wondering it there exists a method to link
to function from other package when I'm trying to write a documentation for new package using roxygen2
.
Something like \link{pck=PACKAGE_NAME, fun=FUNCTION_NAME}
?
5 Answers
You have to type \link[pkg]{function}
e.g. \link[stringi]{stri_c}
-
9
-
5note chapter "alternative documentation workflow" in hadley's book. In order to see the links, you have to rebuild the package, not only re-document.– tjeboCommented Mar 28, 2020 at 13:09
Roxygen2
now also supports documentation written in markdown.
The markdown syntax is for the link is [foo::bar()]
which is translated to
\code{\link[foo:bar]{foo::bar()}}
in the generated .Rd file. (See Roxygen2 vignette.)
Note that you may need to specifically turn on Markdown support by writing Roxygen: list(markdown = TRUE)
in your DESCRIPTION
file, or by putting an #' @md
comment if you want to enable markdown only for a specific man page. This is also explained at the very top of the linked vignette. (Thanks to @Tjebo for the comment)
Note that there are two colons in the markdown version whereas there is only one colon in the Rd version.
-
-
Thank you for the note about enabling markdown! I've seen recommendations elsewhere about using markdown style links and was infuriated when I couldn't get them to work :facepalm:– mattadorCommented Jun 8, 2022 at 22:06
-
You can convert existing documentation using
roxygen2md::roxygen2md()
.– LMcCommented Oct 23, 2023 at 21:13
There are two ways to achieve this, using:
1. .Rd
syntax
From "R packages" book:
\code{\link{function}}
- function in this package.\code{\link[MASS]{abbey}}
- function in another package.\link[=dest]{name}
- link to dest, but show name.\code{\link[MASS:abbey]{name}}
- link to function in another package, but show name.\linkS4class{abc}
- link to an S4 class.
2. markdown syntax
From roxygen2 vignette
roxygen2 comment | description | generated Rd code |
---|---|---|
[func()] |
func() in this package |
\code{\link[=func]{func()}} |
[pkg::func()] |
func() in the pkg |
\code{\link[pkg:func]{pkg::func()}} |
[thing] |
topic in this package | \link{thing} |
[pkg::thing] |
topic in the pkg |
\link[pkg:thing]{pkg::thing} |
[`thing`] |
topic in this package | \code{\link{thing}} |
[`pkg::thing`] |
topic in the pkg |
\code{\link[pkg:thing]{pkg::thing}} |
Remember to put Roxygen: list(markdown = TRUE)
in the DESCRIPTION
Markdown shortcodes available from roxygen2>=6.0.0
-
1
-
1
-
1If you want another link text, use e.g.
[`dgCMatrix`][Matrix::dgCMatrix-class]
– jan-glxCommented Jun 29, 2023 at 13:56
In addition to the answer by potockan:
Some packages document several functions in a single help page. For example, the trim
function from Bioconductor package GenomicRanges is documented in intra-range-methods
(which is also the name of a help page from other packages such as IRanges).
To link to the right page with roxygen2
you can use:
\link[GenomicRanges:intra-range-methods]{trim}
or
\code{\link[GenomicRanges:intra-range-methods]{trim}}
to format the text correctly.
The help page will only show trim
but will link to the right help page.
-
1This was helpful when I wanted to link to the
dplyr
dplyr_tidy_seelct
page.\code{\link[dplyr::dplyr_tidy_select]{tidy-select}
resulted in a warning and broken link, but\code{\link[dplyr:dplyr_tidy_select]{tidy-select}
worked.– LMcCommented Feb 16, 2022 at 18:16
To link to a function, we slightly abuse markdown syntax by using [function()]
or [pkg::function()]
.
Re-document your package by pressing Cmd/Ctrl + Shift + D.
Build and install your package by clicking in the build pane or by pressing Ctrl/Cmd + Shift + B. This installs it in your regular library, then restarts R and reloads your package.
Preview documentation with ?
\code{\link[MASS]{stats}}
, from here (scroll way down).@param
or@family
or so on? There are many that I couldn't find info about them anywhere. For example:[MASS::stats()]
which evaluates to\link[MASS]{stats}
when roxygen creates the .Rd files.