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
Related
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.
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 have written and collected R code on various topics that solve particular problems at hand. I stored the R script/code in .txt files. I have now 100s of them.
How do you keep your R code at hand efficiently?
#Manetheran has the right idea: write a package. It's easy to do (especially with RStudio). Read "Writing R Extensions" and then on top of that learn about roxygen2 (which allows you to document each function in-line and avoid writing .Rd files).
Then you can use devtools to load your package locally, or once it's stable if you think other people can use the functions you can submit your package to CRAN.
I prefer to keep it simple. I use Total Commander and when I need an example which uses some R function, I just do Alt-F7 and search for *.R files which contain the desired string.
I use RStudio and have created two or three basic scripts. I save my much-used functions in the basic script that is most appropriate. Then, at the start of an RStudio script for a project, I source one or more of the basic scripts as is appropriate.
I am looking for a way to embed the fix() function within a script. Basically, here's what I'm currently doing:
I load a certain package. For example, library(PerformanceAnalytics)
I call the fix() function to edit a couple functions within the loaded package. Example, fix(VaR).
Then, using R's built-in editor, I copy-paste my function over the one originally loaded from the package.
Finally, I source in my .R script which calls the above functions I fixed and performs the computations I need.
Essentially, I'd like to streamline Step 3 above. Rather than having to manually type fix(function) and copy-paste over the original functions within the loaded package, I'd rather just have it done within a script I source.
Is there anyway to accomplish this?
FYI, I have reached out to the package's creator and loading a re-compiled version of the package with my modified code is out of the question.
Maybe source your functions and then use assignInNamespace?
EDIT #1:
The above won't work because assignInNamespace doesn't alter objects that have been exported. Instead,
put your functions in a file (foo.R)
load the package
then source(foo.R) or
sys.source(foo.R, envir=attach(NULL, name="myenv"))
Your functions will be higher up on the search list if you load them after the package, so R will find them before getting to the package's functions with the same name.
EDIT #2:
I didn't realize VaR called unexported functions in the namespace. That's why EDIT #1 doesn't work. To get it to work, you would need to explicitly reference all unexported PerformanceAnalytics functions used in VaR (e.g. change VaR.Gaussian to PerformanceAnalytics:::VaR.Gaussian).
See this post on R-devel for a couple other approaches. I couldn't quickly get Prof. Ripley's solution to work (I get the same error as in EDIT #1) and I didn't try Gabor's solution.
You can edit the body directly, discussed here:
What ways are there to edit a function in R?
You can download the packages source from CRAN. Edit the function (it will be found in PackageName/R), then install this package into R and just use it that way.
You can even change the package name in the DESCRIPTION file ... call it "PerformanceAnalytics2", then in R you just library(PerformanceAnalytics2) and use it as you would the original package.