I am working to document a visualization function in a package of mine. For this purpose I would like to have an image embedded through the Rd-file 'funcname.Rd' that could explain various parameters utilized in the function, and which would pop up if user goes to read the package manual PDF or writes '?funcname' in R. Something in the lines of:
'Writing R extensions'-document doesn't seem to address this issue, and the only references I could find were this blog post and this R-devel discussion. The former has a broken link to a package called 'base64' and the latter only addresses various alternatives like including the images in R package vignettes instead. It would be great if this could be CRAN-compatible.
Any advice on how to approach this issue would be appreciated, thanks!
Untested, but look at the R source on GitHub, it would appear they add an image to ?par documentation file in the following manner:
\item{\code{mai}}{A numerical vector of the form \code{c(bottom,
left, top, right)} which gives the margin size specified in
inches.\cr
\if{html}{\figure{mai.png}{options: width="35\%" alt="Figure: mai.png"}}
\if{latex}{\figure{mai.pdf}{options: width=7cm}}
}
The figure appears to be saved in /man/figures.
For more details see the Writing R Extensions section on the topic.
Related
Cross posted from: https://community.rstudio.com/t/link-to-r6-method-from-separate-package-in-help-pages-and-pkgdown/134702
I'm currently writing an R package and would like to link to the help page for an R6 method in a separate package. The page I want to link to is here: https://mc-stan.org/cmdstanr/reference/model-method-sample.html, and there is an .Rd file for the method as well (https://github.com/stan-dev/cmdstanr/blob/master/man/model-method-sample.Rd). Finally, I can also access the help page from R directly with ?cmdstanr::`model-method-sample`.
However, when I try to add a link to my own help page using the normal link to another package syntax described here, [cmdstanr::`model-method-sample`], I get this error:
Warning: Link to unknown topic: cmdstanr::`model-method-sample`
I feel like there must be some way to link to this help page, given that it definitely exists and has an .Rd page, but I haven't found a solution yet. Has anyone else run into this problem or know the solution?
I think you (or Roxygen) are using the wrong syntax for the link. According to Writing R Extensions, the Rd syntax should be:
\link[cmdstanr]{model-method-sample}
I'm not sure how to generate this from Roxygen, but it appears to work as-is if I put it in Roxygen comments.
If you want the link with different text, the syntax is
\link[cmdstanr:model-method-sample]{link text}
In fact, I have the same question than Teema Daniel Laajala, but the answer provided does not work for me.
The question was about displaying images in R package documention.
When I write exactly the same code than in the ?par documentation file, which is :
\item{\code{mai}}{A numerical vector of the form \code{c(bottom,
left, top, right)} which gives the margin size specified in
inches.\cr
\if{html}{\figure{mai.png}{options: width="35\%" alt="Figure: mai.png"}}
\if{latex}{\figure{mai.pdf}{options: width=7cm}}
}
the image does not display and all I can see is : imagenotdisplayed.
Though, I did the exact same code as above, put my image in the folder figures in the folder man...
So I was wondering If I was missing something, like a package I should install or something else...
Thanks for your help !
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.
It is my first experience in writing an R-package. I used roxygen2 by following the instructions given in this link http://kbroman.org/pkg_primer/
Everythig is working fine except few things.. there could be a simpler solution to solve the issues, but I am not finding clues what I am doing wrong. I hope someone here in this blog can give a solution to solve my issues.
First issue is about {\code\link{function-name}} in roxygen2:
In .R script I inlcuded this line:
#' #seealso \code{\link{s2a}}
After documenting (generating .Rd files) there is no hyperlink to s2a ,
in documentation s2a shows like a normal text not like hyperlink..
export(s2a) is listed out in NAMESPACE.
Is there any other place i need to modify ?
Second issue is about data():
I saved the dataset in .Rdata format and placed in the data/ in package directory. I also created the .R script in R/ as like following steps here http://kbroman.org/pkg_primer/pages/data.html
In DESCRIPTION file LazyData: true .
but when I type data(shh) in R console gives a warning message
data(shh)
Warning message:
In data(shh) : data set ‘shh’ not found
Any ideas is of great help:)
It's been a while since you asked this, but I was having the exact same problem with hyperlinks in documentation not appearing correctly, so for anyone who might be having a similar problem: Are you possibly viewing the development documentation? The links don't seem to work there. (You'll know this is the case if you see Using development documentation for your_function_name in your console output when you run ?your_function_name.)
The links should appear in the non-development documentation. To generate this you can try building and reloading your package, for instance by following the steps here: http://r-pkgs.had.co.nz/man.html#man-workflow-2
Can I include some PDF in the pkg/doc folder so that the vignette function works, but no corresponding Rnw, Rtex, etc exists?
I am thinking of slides or documents containing markdown text weaved with R chunks, which have a different build process and hence different file extensions.
The writing R extensions guide suggests that it should be possible to include documents which can not be build at installation time, but the vignette function seems to look for files with special extensions (Rnw, Rtex, etc) and also for a file called vignette.rds.
Any hints are appreciated.
I asked about this several years ago, and while Fritz Leisch is amenable to the idea, he hasn't had the time to implement it.
(Cross-posted from a response I just left on R-help:)
As a workaround, you could include your own xvignette function in your package: see below.
It won't show you indices, but it will pick up any appropriately named file that you include in the inst/doc directory of your
package ...
xvignette <- function(vname,pkg,ext="pdf") {
vname <- paste(vname,ext,sep=".")
fn <- system.file("doc",vname,package=pkg)
if (nchar(fn)==0) stop("file not found")
utils:::print.vignette(list(pdf=fn))
invisible(fn)
}
You'll have to somehow alert your package users to the fact that this alternative documentation exists -- perhaps in the help file for the package itself.
You might fill in the default value of pkg above with your package name to make it easier on the user: I thought about using some variant of getPackageName(environment(xvignette)) to do it automatically, but that seems too complicated ...
Brian Ripley also mentioned in his response to the question that:
At present vignette() means Sweave documents, as only they have
metadata like titles. This is planned to be changed soon.
... but I don't know what "soon" means (it will be about 6 months until 2.14.0 comes out, I think)
edit: http://article.gmane.org/gmane.comp.lang.r.devel/28449 details another workaround (creating a dummy vignette that incorporates the existing PDF file)
edit 2: And
here's what Yihui Xie has to say about including knitr-based vignettes in packages (essentially another "dummy vignette" strategy)
vignette about non-Sweave vignettes from the R.rsp package
This is supported natively as of R 3.0.0, see http://yihui.name/knitr/demo/vignette/.
Instructions to use knitr as vignette engine boil down to:
add %\VignetteEngine{knitr::knitr} to the Rnw source document (note you still need %\VignetteIndexEntry{} as before)
specify VignetteBuilder: knitr in the package DESCRIPTION file
add Suggests: knitr in DESCRIPTION if knitr is needed only for vignettes
See also the official R documentation on that topic.