From: "Duncan Murdoch" <murdoch.duncan at gmail.com>
To: "Chris Evans" <chrishold at psyctc.org>, "r-package-devel" <r-package-devel at 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!