Most likely, I am missing something straight forward. But it appears that examples wrapped in donttest that R check rightly ignores are run during the equivalent check on Travis CI.
Example
Here is some R function documentation using roxygen2:
#' #examples
#' \donttest{
#' library(dplyr)
#'
#' # Write output to a temp file
#' "https://www.datacamp.com/community/tutorials/R-nlp-machine-learning" %>%
#' rawr(to_file = TRUE)
#'
#' }
Line 3536 of logs here
checking examples with --run-donttest ... ERROR
Line 4193:
Error in rawr(., to_file = T) : T used instead of TRUE
Note: the actual R error - using T instead of TRUE - is easily solved - I am just curious as to why the examples were run at all
Note: R CMD check --as-cran passes (0 WARNINGS, 0 NOTES, 0 ERRORS) when run locally
The --run-donttest indicates the examples that a wrapped with \donttest are going to be checked.
I think that you need to wrap it around \dontrun{} instead of \donttest{}. \donttest{} is when the example can be run but it takes a lot of time. On the other hand, \dontrun{} is when the example is likely to return an error. Again, I am not 100% sure about this answer.
Kostas' answer (changing \donttest to \dontrun) solved for me. But I also found another solution, that is to add the following to travis.yml
env:
global:
- _R_CHECK_DONTTEST_EXAMPLES_=FALSE
This example comes from here, which was linked to from an issue here
Related
for some reason pkgdown is failing to parse one of the .Rd files that I have in my package. I found it fails when I add examples to the roxygen2 documentation using either the #examples tag or the #example inst/example/add.R alternative. I minimized my function to two arguments in order to make it more "reproducible" and still getting the same error. Please find bellow the error message, the .Rd file generated using that devtools::document() and the roxygen2 documentation of the function. As you can see I am using a very simple example that should run with no problems... One more thing to say is that when I run devtools::check() all my examples pass, so I don't understand why pkgdown is failing.
Thank you so much for your help.
Best,
Error message
Reading 'man/merge.Rd'
Error : Failed to parse Rd in merge.Rd
i unused argument (output_handler = evaluate::new_output_handler(value = pkgdown_print))
Error: callr subprocess failed: Failed to parse Rd in merge.Rd
i unused argument (output_handler = evaluate::new_output_handler(value = pkgdown_print))
.Rd file
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/merge.R
\name{merge}
\alias{merge}
\title{Merge two tables}
\usage{
merge(x, y)
}
\arguments{
\item{x}{data frame: referred to \emph{left} in R terminology, or \emph{master} in
Stata terminology.}
\item{y}{data frame: referred to \emph{right} in R terminology, or \emph{using} in
Stata terminology.}
}
\value{
a data.table joining x and y.
}
\description{
This is the main and, basically, the only function in joyn.
}
\examples{
x <- c(1, 2)
}
roxygen2 documentation
#' Merge two tables
#'
#' This is the main and, basically, the only function in joyn.
#'
#' #param x data frame: referred to *left* in R terminology, or *master* in
#' Stata terminology.
#' #param y data frame: referred to *right* in R terminology, or *using* in
#' Stata terminology.
#' #return a data.table joining x and y.
#' #export
#' #import data.table
#'
#' #examples
#' x <- c(1, 2)
This error comes from downlit::evaluate_and_highlight (sad it's not reported in the output), and can be fixed by installing the development version of downlit:
library(devtools)
install_github('r-lib/downlit')
It make sense only if you use the git version also from pkgdown, the stable pkgdown (version 1.6.1) runs just fine with the stable downlit. Of course development version of any package can break at any time, but until it doesn't, it's just alright.
I've written a package (myHelpers) that had been using the following function:
#' Negate the \code{\%in\%} function.
#'
#' Use this for the OPPOSITE of \code{\%in\%}.
#'
#' #export
"%not in%" <- function(x, y) !x %in% y
In the past (last year) this worked fine with my package. But now (and I don't know why) with the following:
library(myHelpers)
df1 <- c(1,2,3,4,5)
df2 <- c(4,5)
df1 %not in% df2
Produced the following error:
Error in df1 %not in% df2 : could not find function "%not in%"
I don't know if something's changed when I build the package using roxygen2, but this is frustrating.
When I simple add this to my global environment in my session, everything is fine.
Any idea on how to get this function (with the SPECIAL characters of %) exported and seen with my myHelpers package would be appreciated.
Thanks,
Michael
EDIT 9-13-19 14:07 PST
I'm using RStudio and my shortcut to build the documentation (and the Namespace presumable) with Command+Shift+D. I'm assuming the documentation gets written as it's in the MAN folder for the package. BUT, I get this error in the Build pane:
Warning message:
roxygen2 requires Encoding: UTF-8
AND, when I look in the Namespace file, my function is missing (even tough I'm telling roxygen to export it (with the #export).
Looking for the fix...
EDIT 9-13-19 14:14 PST
FIXED
Added:
Encoding: UTF-8
To Description file...and I had an error that I didn't see. I was using:
#keyword export
Because I had been using #keyword internal for a bit with the function....Now, I changed it to the CORRECT:
#export
And I'm off and running. Thanks for helping with overtired academic discover his mistake.
I am writing an R package and create documentation using roxygen2. I build the package and the documentation using the button Build & Reload in RStudio. According to RStudio's output, it uses devtools::document(roclets=c('rd', 'namespace')) to compile the documentation.
I want to use the #family tag to link together a number of functions in the documentation and this is where my problem occurs. This line
#' #family functions returning some object
is converted in the .Rd file to the following
\seealso{
Other functions.returning.some.object: \code{\link{test2}}
}
I don't want the dots between the words. I have an older package, where this does not happen, even if I recompile the documentation in the exact same setting as I compile the new package. I can see no fundamental difference between this older package and my new attempt.
I have written a very simple test package, where the problem also occurs. It contains a single R file (testpackage.R):
#' Test function 1
#'
#' #param x a number
#'
#' #family functions returning some object
#' #family aggregate functions
#'
#' #export
test1 <- function(x) {
x*x
}
#' Test function 2
#'
#' #param x a number
#'
#' #family functions returning some object
#' #family aggregate functions
#'
#' #export
test2 <- function(x) {
x*x*x
}
The DESCRIPTION file is
Package: testpackage
Type: Package
Title: Package for testing purposes
Version: 1.0
Date: 2015-05-21
Author: Me
Maintainer: Me <me#somewhere.com>
Description: Package for testing purposes
License: GPL-3
NAMESPACE is generated by roxygen. For the documentation test1.Rd, I get:
% Generated by roxygen2 (4.1.1): do not edit by hand
% Please edit documentation in R/testpackage.R
\name{test1}
\alias{test1}
\title{Test function 1}
\usage{
test1(x)
}
\arguments{
\item{x}{a number}
}
\description{
Test function 1
}
\seealso{
Other aggregate.functions: \code{\link{test2}}
Other functions.returning.some.object: \code{\link{test2}}
}
with the unwanted dots in the \seealso section. Clearly, the number of words in the #family tag seems not to matter. I have tried enclosing the text in quotation marks, various kinds of brackets, etc. with no positive effect. Of course, I could edit the Rd files, but this would miss the point of using roxygen2.
R CMD check runs without warnings or errors on testpackage.
Why do these dots appear? And how can I get rid of them?
This is a bug in roxygen2 -- I've logged an issue here. It effectively results from the use of unstack(), which performs some unwanted conversions.
I upgraded to Roxygen 5.0.0 (which is now the CRAN version) and found that the problem went away.
I'm creating a package using devtools and roxygen2 (in RStudio), however after I've built the package my function no longer works as intended. Yet, if I load the function's .R file and run the function from there in RStudio, it works perfectly. I've created another package using this method before and it worked fine (13 functions all working as intended from my other package), yet I cant seem to get this new one to work.
To start creating the package I start with:
library("devtools")
devtools::install_github("klutometis/roxygen")
library(roxygen2)
setwd("my parent directory")
create("triale")
All is working fine so far. So I put my .R file containing my function in the R folder under the triale folder. The .R file looks like this:
#' Trial Z Function
#'
#' This function counts the values in the columns
#' #param x is the number
#' #keywords x
#' #export
#' #examples
#' trialz()
trialz = function(x) {w_id= c(25,x,25,25,25,1,1,1,1,1);
wcenter= c(rep("BYSTAR-1",10));
df1 <<- data.frame(w_id, wcenter);
countit <<- data.table(df1);
view <<- countit[, .N, by = list(w_id, wcenter)];
View(view)}
Again if I were to just run the code from the .R file, and test the function it works fine. But to continue, next I enter:
setwd("./triale")
document()
The triale documentation is updated, triale is loaded, and the NAMESPACE and trialz.Rd are both written so that trialz.Rd is under the man folder, and NAMESPACE is under the triale folder as intended. Next I install triale:
setwd("..")
install("triale")
Which I know works because I get the following:
Installing triale
"C:/PROGRA~1/R/R-31~1.3/bin/x64/R" --vanilla CMD INSTALL \
"C:/Users/grice/Documents/R/triale" \
--library="C:/Users/grice/Documents/R/win-library/3.1" --install-tests
* installing *source* package 'triale' ...
** R
** preparing package for lazy loading
** help
*** installing help indices
** building package indices
** testing if installed package can be loaded
*** arch - i386
*** arch - x64
* DONE (triale)
Reloading installed triale
Package is now built, so I do the following:
library("triale")
library("data.table")
Note whenever I load the package data.table I get the following error message:
data.table 1.9.4 For help type: ?data.table
*** NB: by=.EACHI is now explicit. See README to restore previous behaviour.
However it doesnt seem to affect my function. So now its time to test my function from my package:
trialz(25)
This goes through, and I of course get a populated df1, and countit, but for whatever reason view is always empty (as in 0 obs. of 0 variables).
So I test my work using the dummy code below:
>trialy = function(x) {wid= c(25,x,25,25,25,1,1,1,1,1);
wc= c(rep("BYSTAR-1",10));
df2 <<- data.frame(wid, wc);
countitt <<- data.table(df2);
viewer <<- countitt[, .N, by = list(wid, wc)];
View(viewer)}
>trialy(25)
Even though this is the same exact code with just the names changed around it works. Dumbfounded I open trialz.R and copy the function from there and run it as below, and that works:
> trialz = function(x) {w_id= c(25,x,25,25,25,1,1,1,1,1);
wcenter= c(rep("BYSTAR-1",10));
df1 <<- data.frame(w_id, wcenter);
countit <<- data.table(df1);
view <<- countit[, .N, by = list(w_id, wcenter)];
View(view)}
> trialz(25)
Since I've created a package before I know my method is solid (that package had 13 dif. functions, all of which worked). I just don't understand how a function can work fine as written, yet when I package it, the function no longer works.
Again here is where it stops working as intended when using my package:
view <<- countit[, .N, by = list(w_id, wcenter)];
View(view)}
And my end result should look something like this, if my package worked:
wid wc N
1 25 BYSTAR-1 5
2 1 BYSTAR-1 5
Can anyone explain why view is never populated after I package my function? I've tested it as much as I know how, and my results should be reproducible for anyone thats willing to try it for themselves.
Thanks, I appreciate any feedback.
Your problem here is that "<<-" does not create variables in the global environment but rather in the parent environment. (See help("<<-").)
The parent environment of a function is the environment in which it has been defined. In the case where you defined your function directly in your workspace, this parent environment actually is the same as your workspace environment (namely: .GlobalEnv), which is why your variables are assigned values as you expect them to. In the case where your function is packaged, however, the parent environment is the package environment and not the .GlobalEnv! This is why you do not see your variables being assigned values in your workspace.
Refer to the chapter on environments in Hadley's book and How R Searches and Finds Stuff for more details on environments in R.
Note that doing this would not be considered a proper debugging technique, to say the least. In general, you never want to use the "<<-" operator.
For options on debugging R code, see, e.g., this question. I, in particular, like the debugonce function very well. See ?debugonce.
I forgot one important part when editing my description file in that I for got to add
Imports: data.table
Also the NAMESPACE file needed to include the data.table package as an import as well, like so:
import(data.table)
export(Z)
export(AS) .... etc.
Doing this ensures that whenever a function within your package uses a function from another package, that (second) package is called up before your code is executed.
I'm writing a geocoding function right now that relies on having a Bing Maps Key. Obviously I'd rather not publish mine, and the examples fail without one.
How do I include an example for users to run manually, but not have it executed during R CMD check?
Use \dontrun{}
#'#examples
#'\dontrun{
#'geocode("3817 Spruce St, Philadelphia, PA 19104")
#'geocode("Philadelphia, PA")
#'dat <- data.frame(value=runif(3),address=c("3817 Spruce St, Philadelphia, PA 19104","Philadelphia, PA","Neverneverland"))
#'geocode(dat)
#'}
You can use \donttest{} to your example. The snippet will be provided in your documentation, but won't get tested with the R CMD Check.
For more info --> ?example
#' #example
\donttest{
2^2
}
This 2^2 won't get run when you run devtools::check()
EDIT
Per the latest release notes or NEWS for R 4.0.0, examples within \donttest{} will now be tested by default. This can, however, be overridden by setting environment variable _R_CHECK_DONTTEST_EXAMPLES_ to FALSE.
R CMD check --as-cran now runs \donttest examples (which are run by example()) instead of instructing the tester to do so. This can be temporarily circumvented during development by setting environment variable R_CHECK_DONTTEST_EXAMPLES to a false value.
According to this GitHub issues discussion (credited here), Hadley Wickham noted that
Generally, now if you don't want to run tests on CRAN \dontrun{} is more likely to work, but using \dontrun{} may cause initial submission to fail.
There are other ways as well that will let you continue to use donttest{}, refer the aforementioned discussions for the workarounds.
For those who are using #example path/to/example.R instead of the #examples tag you can use the \dontrun environment directly in the example.R file. For example
# example.R
\dontrun{
# this is a long running example
for(i in seq(1, 1e5)) { lm(mpg ~ wt, data = mtcars) }
}
# some other shorter example
2 + 2
Ari, I also use roxygen2 (version 4.1.0). The following is the end of my roxygen2 mark-up in my function (gctemplate) definition till the beginning of the real part.
#' #examples
#' ## List all G-causalities in a VAR system of 5 variables that will be searched in the pattern of 1
#' ## causer (like-independent) variable and 2 like-dependents conditional on 5-(1+2)=2 of the remaining
#' ## variable(s) in the system. Variables are assigned to numbers 1 to nvars.
#' ## "1 2 5 3 4" in the resulting line of gctemplate is to indicate the
#' ## (conditonal, partial, etc.) G-causality from variable 1 to variables 2 and 5
#' ## conditonal on variables 3 and 4.
#' # gctemplate(5,1,2)
#' ## The number of all G-causalities to be searched in the above pattern.
#' #dim(gctemplate(5,1,2))[[1]]
#' #importFrom combinat combn
#' #export
gctemplate <- function(nvars, ncausers, ndependents){
...
I know GSee's dontrun method.
In my technique, the numerical example and the text explaining the numerical example are both comments. I use indentation to make difference between these two; Notice there are 1 sharp and 2 sharps respectively after "#'". I always use the above "#' ## / #' #" technique in my packages. The user is left to copy-paste operation whenever s/he wanna test the function. This technique is - according to me - more parallel with the classical comment bombardment of the software coding philosophy.
\dontrun{}
Is the correct function. See here:
For the purpose of illustration, it’s often useful to include code that causes an error. \dontrun{} allows you to include code in the example that is not run. (You used to be able to use \donttest{} for a similar purpose, but it’s no longer recommended because it actually is tested.)
Source: https://r-pkgs.org/man.html?q=donttest#man-functions