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

[Chris Evans]

Brilliant: exactly what I needed.  I see a happy hour tomorrow morning sorting those.

Many thanks (again) Duncan and very best to all here!

Chris

----- Original Message -----
> From: "Duncan Murdoch" <murdoch.duncan using gmail.com>
> To: "Chris Evans" <chrishold using psyctc.org>, "r-package-devel" <r-package-devel using r-project.org>
> Sent: Saturday, 10 April, 2021 21:20:40
> Subject: Re: [R-pkg-devel] Advice on identifying parsing failures with examples when trying to pkgdown my package

> 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!
>> 

-- 
Chris Evans (he/him) <chris using psyctc.org> Visiting Professor, University of Sheffield <chris.evans using sheffield.ac.uk>
I do some consultation work for the University of Roehampton <chris.evans using roehampton.ac.uk> and other places
but <chris using psyctc.org> remains my main Email address.  I have a work web site at:
   https://www.psyctc.org/psyctc/
and a site I manage for CORE and CORE system trust at:
   http://www.coresystemtrust.org.uk/
I have "semigrated" to France, see: 
   https://www.psyctc.org/pelerinage2016/semigrating-to-france/ 
   https://www.psyctc.org/pelerinage2016/register-to-get-updates-from-pelerinage2016/

If you want an Emeeting, I am trying to keep them to Thursdays and my diary is at:
   https://www.psyctc.org/pelerinage2016/ceworkdiary/
Beware: French time, generally an hour ahead of UK.