Possible to Create Rd Help Files for Objects Not in a Package

R package documentation: link to a whole package, not function

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.

R object documentation: Package documentation as first item

In order to ensure that the package documentation entry is first in the manual, you need its name to be <packagename>-package (where you replace <packagename> with the name of your package). Here you could accomplish that by changing

#' @name TestPackage

to

#' @name TestPackage-package

Why is this the case? Well, as always when you run into some strange corner of R package development, the best thing you can do is to consult the Writing R Extensions manual. Here, we'd want to look at Section 2.1, Rd format (the documentation files in R are in a format called Rd; roxygen creates the Rd files in man/ for you). Specifically, in Section 2.1.1, we see

\name{name}

name typically¹⁰¹ is the basename of the Rd file containing the documentation. ... Entries in the package manual will be in alphabetic¹⁰² order of the \name entries.

That footnote 102 tells us

in the current locale, and with special treatment for LaTeX special characters and with any ‘pkgname-package’ topic moved to the top of the list.

So, you have to name the Rd file as pkgname-package to move it to the top of the manual.

Where are objects stored in R packages?

Variables can also be created in a normal R script of the package with foo <- new.env() and then populated with content, e.g.

foo <- new.env()

foo <- data.frame(
  x=1:10,
  y <- rnorm(10)
)

It is also possible to make the internal data hidden, e.g. .foo. As an example CRAN package marelac uses this mechanism in files aaa.R, gas_schmidt.R and some others.

Another possibility is a file sysdata.rda that can be placed in the /Rfolder, see: https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Package-subdirectories

Non-file package-anchored link(s) in documentation object

It seems that, if you use links of the form \code{\link[pkg]{foo}} pointing to help pages containing several functions, the link should point only to the core function.

For example, say the functions foo_1 and foo_2 are described in the same help page and foo_1 is the main function (i.e. appearing in the top left corner of the help page).

To create a link to foo_2, you should use \code{\link[pkg:foo_1]{foo_2}}.

See this GH issue and this reference in writing R extensions.

R won't find objects

So all I needed to do was install the package instead of using the .R and .Rd files on my working directory.

R help page as object

So below what I hacked together. However I yet have to test it on many help files to see if it generally works.

Rd2list <- function(Rd){
    names(Rd) <- substring(sapply(Rd, attr, "Rd_tag"),2);
    temp_args <- Rd$arguments;

    Rd$arguments <- NULL;
    myrd <- lapply(Rd, unlist);
    myrd <- lapply(myrd, paste, collapse="");

    temp_args <- temp_args[sapply(temp_args , attr, "Rd_tag") == "\\item"];
    temp_args <- lapply(temp_args, lapply, paste, collapse="");
    temp_args <- lapply(temp_args, "names<-", c("arg", "description"));
    myrd$arguments <- temp_args;
    return(myrd);
}

getHelpList <- function(...){
    thefile <- help(...)
    myrd <- utils:::.getHelpFile(thefile);
    Rd2list(myrd);
}

And then you would do something like:

myhelp <- getHelpList("qplot", package="ggplot2");
cat(jsonlite::toJSON(myhelp));

---

Related Topics