1

I am working on a package in R, and am looking for a way to document the sources of external data stored in the inst/extdata folder. I know that data in the /data folder can be documented with roxygen as per this SO post.

The trouble seems to be that external data is not exported into the namespace of the package, and therefore tying an roxygen help document to it poses an issue. Is there a way to overcome this and to document external data similar to the method for items in the /data folder?

jangorecki
  • 16,384
  • 4
  • 79
  • 160
Rob
  • 265
  • 2
  • 11
  • A typical approach would be creating a function to interface with / download the external data source, and documenting the data as part of the function. – Allan Cameron Oct 31 '20 at 20:17
  • Relevant: https://stackoverflow.com/questions/57396392/warning-variables-with-usage-in-documentation-object-fang-but-not-in-code – Hong Ooi Nov 01 '20 at 09:21
  • You can write R documentation files .Rd directly, not using roxygen, then you can write documentation on any topic/alias – jangorecki Nov 02 '20 at 17:21
  • @jangorecki is there a way to then connect the documentation to the data file, such that it comes up with the '?' syntax in R? – Rob Nov 03 '20 at 20:14
  • yes, you put the name as `alias` in Rd – jangorecki Nov 04 '20 at 07:12

1 Answers1

1

Here is the reproducible (on linux) example of solution I provided in comments.

Code below will create minimal package

  • defining dummy DESCRIPTION file
  • example ext/data/data1.csv csv data file
  • example man/data1.Rd R documentation file

Then it will build and install package.

mkdir -p my.pkg
cat > my.pkg/DESCRIPTION <<EOL
Package: my.pkg
Type: Package
Title: My pkg
Version: 1.0.0
Description: Example my pkg.
License: GPL-3
EOL
mkdir -p my.pkg/inst/extdata
cat > my.pkg/inst/extdata/data1.sv <<EOL
a,b,c
1,a,2.5
2,b,5.5
EOL
mkdir my.pkg/man
cat > my.pkg/man/data1.Rd <<EOL
\name{data1}
\alias{data1}
\alias{data5}
\title{
my data
}
\description{
desc of data.
}
EOL
R CMD build my.pkg
R CMD INSTALL my.pkg_1.0.0.tar.gz

Now see that manual can be found

Rscript -e 'library(my.pkg); ?data1'

Rscript -e 'library(my.pkg); ?data5'

As you can see we can refer to documentation of extdata using any name defined in alias inside Rd file.

jangorecki
  • 16,384
  • 4
  • 79
  • 160
  • 1
    Thanks, that worked, and was fine with the R CMD CHECK on the package as well. I imagine there probably is a way to still build this file from .R with roxygen2, but perhaps not necessary. Cheers – Rob Nov 05 '20 at 21:59