[R-pkg-devel] Advice on identifying parsing failures with examples when trying to pkgdown my package

[Duncan Murdoch]

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!