Uninformative error (and/or problem with pkgdown:::build_site_external())

[jennybc]

I was experimenting with pkgdown in some toy packages for the R Packages book, where I recommend the add-in as a nice way to preview a local pkgdown site. It's a super simple toy package with 1 function and a couple of vignettes/articles that only attach the package.

The add-in calls pkgdown:::build_site_external().

build_site_external() seems to assume that the package has already been installed, which apparently was not true in my case.

It proceeds to fail in a really confusing way:

== Building pkgdown site =======================================================
Reading from: '/Users/jenny/tmp/ethel'
Writing to:   '/Users/jenny/tmp/ethel/docs'
-- Initialising site -----------------------------------------------------------
-- Building home ---------------------------------------------------------------
Writing '404.html'
-- Building function reference -------------------------------------------------
Reading 'man/ethel.Rd'
-- Building articles -----------------------------------------------------------
Reading 'vignettes/alfa.Rmd'
-- RMarkdown error -------------------------------------------------------------
Quitting from lines 18-19 (alfa.Rmd) 
--------------------------------------------------------------------------------
Error: 
! in callr subprocess.
Caused by error in `map(.x, .f, ..., .progress = .progress)`:
! In index: 1.
ℹ See `$stdout` for standard output.
Type .Last.error to see the more details.

It's awfully hard to guess that the problem is that the toy package (ethel) has never been installed and that's why we can't render the vignettes.

I did suspect that that was the problem. Trying to build a single vignette produces a much better error message:

> pkgdown::build_article("alfa")
Reading 'vignettes/alfa.Rmd'
-- RMarkdown error ------------------------------------------------------------------------------
Quitting from lines 18-19 (alfa.Rmd) 
-------------------------------------------------------------------------------------------------
Error in `render_rmarkdown()`:
! Failed to render RMarkdown
Caused by error:
! in callr subprocess.
Caused by error:
! there is no package called 'ethel'
Run `rlang::last_error()` to see where the error occurred.

I don't know what the correct resolution is.

On one hand, maybe the fix is just to make there is no package called 'ethel' bubble up.

Or should build_package_external() check that the target package has been installed? That leads me to another dilemma, which is it seems quite possible that the documentation and examples will be built from current source, whereas vignettes and articles are built from whatever version was last installed.

I think I'm surprised that build_package_external() defaults to devel = TRUE. It seems odd to bother to build in a separate process, but to not bother to install current source in a temporary library.

[jennybc]

Behaviour-wise, I think I expected the addin to basically behave like build_site(), i.e. to share its defaults. In the book, I presented pkgdown::build_site() and the addin as sort of drop-in equivalents for each other.

[hadley]

Yeah, I don't see why it shouldn't just call build_site()