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.?
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.
Related
I've just created my first package and I have some problems with description. I was trying to use vignette with code usethis::use_vignette("introduction") and it creates introduction to package and to included functions. To see it I pressed "knit" button and it works, look nice etc.. I also create new R script and use library('mypackage') and all function work, but I have no idea how can I see my vignette (description of package and functions). For example in packages like ggplot2 or graphics you can just put ??ggplot2, ??graphics to just see description of package. But putting ??mypackage I see in R help 'No results found'. How can I see this created vignette not in model building tools, but in new script which refers to my package.
RStudio's build and reload does not build vignettes by default. You'll need to use devtools::build() to ensure vignettes are built. If you are using Github to install the package use devtools::install_github("package", build_vignettes = TRUE)
I'm developing an R package, and I'm trying to make a link from the manual of the package to its vignette (a pdf). I've make this in the R function code, and it works:
\link[=../doc/package.pdf]{package's User Manual}
The problem is that the devtools::check() complains with a warning, which also causes a delay in the process of revision when uploading to CRAN...
* checking Rd cross-references ... WARNING
Missing link or links in documentation object 'package.Rd':
'../doc/package.pdf'
Is there a better way of linking from man to vignette? or it is not correct to do so? As the pdf can contain more graphical information, it seems desirable to be able to link to it.
If you use pkgdown to make a website out of your package, then you can directly link to the url of the specific vignette.
Or you can just write
Run \code{vignette("NAME_OF_YOUR_VIGNETTE", package = "NAME_OF_YOUR_PACKAGE")} to see the corresponding vignette.
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}?
You have to type \link[pkg]{function} e.g. \link[stringi]{stri_c}
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.
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
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.
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 ?
I am wondering if there is a possibility, during writing a package in R, to link to the documentation page in R that has no functions included but has only package-info?
For example \link[stats]{stats-package.R}?
One of the possibillities is \link[stats]{stats-package} without .R extansion (but it will link to stats-package page). If you just want to link the package use \pkg{package} e.g. \pkg{stats}. For more info try Writing R Extensions
I'm writing a vignette for one of my packages.
In this vignette, I would like to demonstrate how this package can interact with other packages that are not being imported by the NAMESPACE or by the Imports section of the DESCRIPTION file.
So, I'm putting a require call to use these external packages in my vignette, but of course I got the following NOTE when I try to R CMD check the package:
* checking for unstated dependencies in vignettes ... NOTE
‘library’ or ‘require’ call not declared from: ‘RColorBrewer’
Is there any way around this, or should I either import these external packages or "fake" the vignette using eval=FALSE?
Put it in Suggests: of your DESCRIPTION file.
From p. 6 of the R extensions manual:
The ‘Suggests’ field uses the same syntax as ‘Depends’ and lists
packages that are not necessarily needed. This includes packages used
only in examples, tests or vignettes (see Section 1.4 [Writing package
vignettes], page 26), and packages loaded in the body of functions.
E.g., suppose an example from package foo uses a dataset from package
bar. Then it is not necessary to have bar use foo unless one wants to
execute all the examples/tests/vignettes: it is useful to have bar,
but not necessary. Version requirements can be specified, and will be
used by R CMD check.
In addition if the vignette properly depends on that package, there should be a
% \VignetteDepends{...}
statement in the vignette itself: Sweave, Part II: Package Vignettes, R News 3/2 (Oct. 2003), 21 - 24.
However, your case possibly is a bit different:
I use if (require ("pkgxy")) without % \\VignetteDepends{pkgxy} (Suggests: pkgxy in the DESCRIPTION is needed anyways) for some things I want to show but where I don't want to force the user to have all the suggested pacakges installed. I put a box at the beginning of the vignette where I report which of those packages are available and if a package is not available when the vignette is built, an "pkgxy is needed to do this" text is put into the vignette.
The "introduction" vignette of package hyperSpec is an example (to find out how it actually works, you need not only the .Rnw but also some more definitions).