I have a question about creating an .Rd file for my R package using the roxygen2 package.
It is clear to me that, for documenting R functions, I can use C-c C-o in emacs to generate comments above the function, and then fill them out, followed by roxygenize("pkg"). In this way, I have .Rd files for the R functions. However, I am not sure how can I get .Rd file for the data examples and the package itself? Currently, I am using prompt("data") to generate data.Rd and promptPackage("pkg") to generate pkg-package.Rd. I have to put these files into the man folder, and then edit them separately. How can I document data and package in a similar way like documenting R functions using roxygen2?
Thank you very much!
For data, see this previous question on SO which suggests:
#' This is data to be included in my package
#'
#' #name data-name
#' #docType data
#' #author My Name \email{blahblah##roxygen.org}
#' #references \url{data_blah.com}
#' #keywords data
NULL
I would suspect that you can do the same for pkg-package.Rd. If it must be in roxygen format, consider
a manual translation or
the rd2roxygen package.
Related
I have created my own package with description file and help paper for every function.
Now if I code ?mypackage::myfunction R displays help paper to myfunction. But when I code ?mypackage R displays "No documentation for ‘mypackage’ in specified packages and libraries:" :(
In case you are not using roxygen2 (but you probably should), you need to create a .Rd file with the general mandatory fields, including a \docType{package}. See section 2.1.4 of the Writing R Extensions.
Apart from the mandatory \name and \title and the pkgname-package
alias, the only requirement for the package overview page is that it
include a \docType{package} statement. All other content is optional.
We suggest that it should be a short overview, to give a reader
unfamiliar with the package enough information to get started. More
extensive documentation is better placed into a package vignette (see
Writing package vignettes) and referenced from this page, or into
individual man pages for the functions, datasets, or classes.
Assuming you are using Roxygen2 to generate your documentation, somewhere you will need something like this saved in a .R file.
#' Title
#'
#' Description
#'
#' #docType package
#' #name varbinq
NULL
This will create a help file for your package that can be accessed when you type ?varbinq
For more information see this section of Hadley Wickham's book entitled R Packages.
If you are using the roxygen2 package for documenting your package called "mypackage", the documented way to do this is to write this code in a file named "mypackage.R":
#' Generate R documentation from inline comments.
#'
#' Roxygen2 allows you to write documentation in comment blocks co-located
#' with code.
#'
#' The only function you're likely to need from \pkg{roxygen2} is
#' \code{\link{roxygenize}}. Otherwise refer to the vignettes to see
#' how to format the documentation.
"_PACKAGE"
You will then be able to retrieve your package's help page using:
??mypackage
I am using RStudio to create a package for a piece of data analysis I'm doing. To put my raw data into the package, I'm using devtools::use_data_raw() as per this article.
I have a script load-raw-data.R that loads the raw data and assembles it into a dataframe, then calls devtools::use_data() on this dataframe to add it to the package. load-raw-data.R is in /data-raw not /R, as per the article. I've added documentation to the functions in this script via a roxygen2 skeleton, however when I build the documentation the .Rd files for these functions are not built. I presume this is because roxygen2 is only looking in /R. Is there a way to tell roxygen2 to look in /data-raw as well? Or have I misunderstood something along the way?
Update: following #phil's suggestion
#phil - thanks - I tried this for one of the functions (load_data_files) in the load-raw-data.R script (see below for the documentation added to R/data.R), but on rebuilding the package I get an error: 'load_data_files' is not an exported object from 'namespace:clahrcnwlhf'. I have included the #export tag in the documentation in R/data.R. Any thoughts on how I might resolve this?
`# This script loads the individual component files of the raw dataset
# and stitches them together, saving the result as an .RData file
#' load_data_files
#'
#' load_data_files loads in a set of Excel files as dataframes
#'
#' #param fl list of paths of the files to be loaded
#'
#' #return A list of dataframes, one for each of the file paths in fl.
#' #export
"load_data_files"`
When developing an R package, it is common for me to just turn on Packrat and use a localized repository, and develop as I explore in a session. But when publishing the package, it is a big headache to recall and manually add every dependency I have used in the developed package. Is there a (semi-)automatic way to do this?
For example, in NodeJS development, we can just use npm install --save and the dependency will be added automatically to package.json.
Yes, use roxygen2 to generate your NAMESPACE file.
Example way to generate package level documentation:
#' #details
#' \tabular{ll}{
#' Package: \tab \cr
#' Type: \tab Package\cr
#' Version: \tab 1.0.0\cr
#' Date: \tab 2016-05-15\cr
#' License: \tab MIT \cr
#' }
#' #useDynLib pkg
#' #importFrom Rcpp evalCpp
#' #importFrom methods is
#' #importFrom stats ts as.ts is.ts
#' #import ggplot2
"_PACKAGE"
Note: I tend to keep my import statements together in the package-level documentation. You can use these same statements within function documentation.
Use #importFrom <pkg> <function1> <function2> for specific imports.
Otherwise, use #import <pkg> for all functions in a given package.
Edit
To lock it to a specific version, you will need to modify your DESCRIPTION file's Imports: section like so:
Imports:
Rcpp (>= 0.12.5),
scales (<= 0.4.0),
grid (== 0.7-4),
stats
A common way to do this (although not one that's used much by "old school" R programmers, who as far as I know maintain their NAMESPACE files by hand ...) is to manually insert roxygen2 #importFrom statements in the code ... e.g.
# returns a true family() object iff one was given
## to glmmTMB() in the first place ....
##' #importFrom stats family
##' #export
family.glmmTMB <- function(object, ...) {
object$modelInfo$family
}
although it would certainly be helpful to have an automated system, to provide hints if nothing else. Certainly maintaining dependencies in this way (making sure to add #importFrom statements as needed for every function that has a dependency) is better than trying to keep track of when dependencies are (still) needed after developing the code.
#import and #importFrom (which translate to import and importFrom statements) are both legal, the R extensions guide says
Using importFrom selectively rather than import is good practice and recommended notably when importing from packages with more than a dozen exports.
("good practice" translates to "CRAN maintainers will yell if you don't" ...)
I don't know if there's a way to do versioned importFrom statements: R puts package version dependencies in the Imports: field in the DESCRIPTION file and importFrom statements in the NAMESPACE file: roxygen2 generates this information automatically, but I don't think the mapping from roxygen2 directives to NAMESPACE/DESCRIPTION information is fine-grained enough to support this ...
Running R CMD check --as-cran gives hints about functions from recommended packages that need to be imported.
I am using devtools to build R package, and there are some functions that are NOT designed to be visible to end-users. However, since these functions involve calling C codes by .Call, so that I have to write #useDynLib above the function for automatic generation of .Rd files. In that way, when I build the package, even I did NOT include the #export for those functions, they nonetheless appear in the help document... Is there a way to suppress those functions even if they have been documented? Thanks!
According to Hadley's comments, use #keywords internal will make the function invisible to end-users. Details can be found here in the wiki pages of devtools.
The wiki linked in the accepted answer no longer discusses #keywords internal (as of April 2016). In case it's helpful for someone to see an example:
# multiplyBy3
#' This is an example of an internal function called \code{multiplyBy3()}
#'
#' Sometimes you want internal functions as part of an R Package built with
#' RStudio and roxygen2, but you don't want .Rd files created for them
#' or to have them be visible in the help document following the build process
#'
#' #keywords internal
#'
#' #param base_num The number to multiply by three
#'
#' #import jsonlite
#'
#' #return Returns a numeric vector
#'
multiplyBy3 <- function(base_number) {
stopifnot(is.numeric(base_number))
return(base_number * 3)
}
Key bits: do not include #export and do include #keywords internal
For me, #keywords internal did not work (roxygen2 6.1.1). I was able to achieve the desired result using the following in my roxygen comments:
#noRd
While working on my first R package a noticed that when the package structure gets created in the man directory "man" there is a documentation file for each function/method in the code.
In order to stay DRY (don't repeat yourself) I used some functions as "auxiliary" functions in loops or iteration. How can I tell R that I do not want to provide any documentation for them given that they should not be called directly by the end user?!?!
Use the roxygen2 and devtools packages to document your functions and build your package.
#' Function 1 Title
#'
#' Describe what function 1
#' does in a paragraph. This function
#' will be exported for external use because
#' it includes the #export tag.
#'
#' #param parameter1 describe the first parameter
#' #param parameter2 describe the second parameter
#' #examples
#' function1(letters[1:10], 1:10)
#' #export
function1 <- function(parameter1, parameter2) {
paste(parameter1, parameter2)
}
#' Function 2 Title
#'
#' Description here. This will not
#' be added to the NAMESPACE.
#'
#' #param parameter1
function2 <- function(parameter1) {
parameter1
}
Once you have all your documentation, use the tools in the devtools package to build, document, and check your package. It will automatically update the man files and DESCRIPTION, and add / remove functions from the NAMESPACE.
document()
build()
check()
I also recommend using the rbundler package to control how you load packages.
If you do not export them via the NAMESPACE you are not expected to provide documentation.
Another (older) was is too simple create one, say, internal.Rd and define a bunch of \alias{foo}, \alias{bar}, \alias{frob} and that way codetools is happy too.
thanks #Jojoshua-ulrich and #dirk-eddelbuettel
According to "Writing R Extensions":
The man subdirectory should contain (only) documentation files for the objects in the package in R documentation (Rd) format. The documentation filenames must start with an ASCII (lower or upper case) letter or digit and have the extension .Rd (the default) or .rd. Further, the names must be valid in ‘file://’ URLs, which means9 they must be entirely ASCII and not contain ‘%’. See Writing R documentation files, for more information. Note that all user-level objects in a package should be documented; if a package pkg contains user-level objects which are for “internal” use only, it should provide a file pkg-internal.Rd which documents all such objects, and clearly states that these are not meant to be called by the user. See e.g. the sources for package grid in the R distribution for an example. Note that packages which use internal objects extensively should not export those objects from their namespace, when they do not need to be documented (see Package namespaces).
By the way, is there any convention to include comments in the code so that man grabs the function description, arguments description etc directly from the code?