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

[Chris Evans]

Just a quick follow-up on this to have a clarification in the thread.  Duncan's suggestions put me straight 
but it seems that at least in my current set up (Rstudio 1.4.1103, R 4.0.5 on Ubuntu 20.04) the preview 
of the Rd file doesn't remove the "\" escapes if I put them into the Roxygen code examples.  However, it also 
seems that if I leave "%>%" as is there (and sort out my other messes that Duncan pointed out!) that 
everything goes fine so I now I have very pleasing (at least to me!) pkgdown site for my package at
https://cecpfuns.psyctc.org.  

At times the learning curve involved in developing the package has seemed tough but, with help from this list,
it is really starting to feel useful, and I'm sure that it was absolutely the right thing to do.

Very best all,

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.