[R-pkg-devel] Advice on identifying parsing failures with examples when trying to pkgdown my package
On 10/04/2021 3:28 p.m., Chris Evans wrote:
My beginner package https://github.com/cpsyctc/CECPfuns is evolving slowly and I had no problems (that I could see) with the help pages created through roxygen. Today I came back to try using pkgdown to ... pkgdown the package. So I used a copy of the package directory and ran: usethis::use_pkgdown() and then pkgdown::build_site() That produced the start of exactly what I wanted as a nicely pkgdown'ed site. However, the console showed error messages for three examples (which, as I say, all seem to produce OK html help pages through the usual roxygen processing). The error message was Failed to parse example for topic and sure enough the examples section in the pkgdown docs html was empty. If anyone wants to look at one of the functions, checkAllUnique was one of the three that threw the errors. I tried some searching and the most pertinent seeming page I hit was this: https://github.com/r-lib/pkgdown/issues/1149 where Hadley Wickham says "That's not valid .Rd code because you didn't escape the Rd comment symbol" which may well be my problem too ... but I don't understand the advice (sorry!)
In Example code, % needs to be escaped, or it will be interpreted as a comment. Sometimes that means the examples just compute the wrong thing, e.g. A %*% b is parsed as A when the rest of the line is ignored as a comment. Sometimes it makes the code illegal. I don't know which you're seeing.
When I tried to tweak one of those functions by inserting a lot of "#" to mask results, i.e. replaced #' [1] something with: #' # [1] something (as I probably should have done that in the examples I have, they are dontrun examples so I hadn't noticed).
pkgdown tries to parse \dontrun examples, so this was a good thing, but
I think you missed some: e.g. in checkAllUnique.Rd, I see this around
lines 55-60:
\examples{
\dontrun{
### letters gets us the 26 lower case letters of the English alphabet so
should test OK
checkAllUnique(letters)
[1] TRUE
### good!
That line containing TRUE is not legal R code, so should be commented.
You can find these one by one by copying the text from the Rd example
section into a file, and trying to parse that file, e.g.
Put this in "test.R":
### letters gets us the 26 lower case letters of the English alphabet
so should test OK
checkAllUnique(letters)
[1] TRUE
### good!
then run parse("test.R"):
Error in parse("test.R") : test.R:3:1: unexpected '['
2: checkAllUnique(letters)
3: [
^
You can do it for a file at a time by loading the test.R file into
RStudio; it'll put markers beside each syntax error. Unfortunately, it
thinks
checkAllUnique(tmpTib \%>\% pull(1))
is a syntax error: those escapes are required in Rd, but are illegal in R.
I don't know if there's a way to do it directly from the Roxygen source.
Duncan Murdoch
However, when I reran pkgdown::build_site() I got a new error message that is, to me, thoroughly confusing: Error in utils::modifyList(meta, override) : is.list(x) is not TRUE At that point I decided to back out and come here and ask the question in the subject line!