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

[Duncan Murdoch]

Here's a better way to do the file-at-a-time check:

Load the .Rd file in RStudio, and click on Preview.  Copy the whole 
examples section to a test.R file.  RStudio will mark all the syntax 
errors, but won't be fooled by the \% escapes, since the Preview handled 
them.

Duncan Murdoch

On 10/04/2021 4:01 p.m., Duncan Murdoch wrote:
> 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!
> 
>