[R-pkg-devel] how to use pkgdown::build_site() with a project using S7 with a specialized plot()?

[Daniel Kelley]

# Question

Is there an online example online of specializing `plot()` for S7 objects, such that `pkgdown::build_site()` will produce webpages?  I ask because I find lots of users (of other packages) tend to consult websites made with pkgdown, rather than using the online help within R.  I think the problem I am having (discussed in the following sections) has to do with my specialization of plot().  I say that because when I was using S3 objects in an earlier version of my package, `pkgdown::build_site()` worked as intended.

# Background

In my 'mooring' package (https://github.com/dankelley/mooring/tree/S7), I am writing code like (https://github.com/dankelley/mooring/blob/f70b53ca12e88968f65710c205b50a64f750a99d/R/plot.R#L69)

```R
#' @aliases plot.mooring
#' ETC
`plot.mooring::mooring` <- plot(ETC) ETC
```

to handle objects made with (https://github.com/dankelley/mooring/blob/f70b53ca12e88968f65710c205b50a64f750a99d/R/oo.R#L2)

```R
mooringS7 <- S7::new_class("mooring",
    package = "mooring",
ETC
```

Built up in Rstudio, with Roxygen2 being used to create documentation, things seem to work, e.g.

```R
m <- mooring(anchor(), wire(length = 80), float(), waterDepth = 100)
plot(m)
```

produces a plot as intended, and

```R
?plot.mooring
```

produces documentation as intended.

*However* I encounter a problem comes when I try building a website with

```R
pkgdown::build_site()
```

This yields results as in the next section.  (I apologize for the length. I'm including the whole thing because I thought that would be less bothersome than writing another email to the list.)

I am not sure how to find the problem, and so I hope that someone on this list can point out an example of how to set up `plot()` to work with S7 objects, in such a way that documentation can be created with Roxygen2 and websites can be made with `pkgdown::build_site()`.

# What pkgdown::build_site() gives

```
> library(pkgdown)
> build_site()
Warning: Failed to parse usage:

S3method(`plot`, ``mooring::mooring``)(
  x,
  which = "shape",
  showInterfaces = TRUE,
  showDepths = FALSE,
  showLabels = TRUE,
  showDetails = FALSE,
  fancy = FALSE,
  title = "",
  mar = c(1.5, 3.5, 3.5, 1),
  mgp = c(2, 0.7, 0),
  xlim = NULL,
  xaxs = "r",
  yaxs = "r",
  type = "l",
  debug = 0,
  ...
)

-- Installing package into temporary library ----------------
== Building pkgdown site =======================================================
Reading from: '/Users/kelley/git/mooring'
Writing to:   '/Users/kelley/git/mooring/docs'
-- Initialising site -----------------------------------------------------------
-- Building home ---------------------------------------------------------------
Writing '404.html'
-- Building function reference -------------------------------------------------
Error: 
! in callr subprocess.
Caused by error in `map2(.x, vec_index(.x), .f, ...)`:
! In index: 1.
ℹ See `$stdout` for standard output.
Type .Last.error to see the more details.
> .Last.error
<callr_error/rlib_error_3_0/rlib_error/error>
Error: 
! in callr subprocess.
Caused by error in `map2(.x, vec_index(.x), .f, ...)`:
! In index: 1.
ℹ See `$stdout` for standard output.
---
Backtrace:
1. pkgdown::build_site()
2. pkgdown:::build_site_external(pkg = pkg, examples = examples, run…
3. callr::r(function(..., cli_colors, pkgdown_internet) { …
4. callr:::get_result(output = out, options)
5. callr:::throw(callr_remote_error(remerr, output), parent = fix_…
---
Subprocess backtrace:
 1. pkgdown::build_site(...)
 2. pkgdown:::build_site_local(pkg = pkg, examples = examples, run_do…
 3. pkgdown::build_reference(pkg, lazy = lazy, examples = examples, …
 4. pkgdown::build_reference_index(pkg)
 5. pkgdown::render_page(pkg, "reference-index", data = data_referen…
 6. pkgdown:::render_page_html(pkg, name = name, data = data, depth =…
 7. utils::modifyList(data_template(pkg, depth = depth), da…
 8. base::stopifnot(is.list(x), is.list(val))
 9. pkgdown:::data_reference_index(pkg)
10. meta %>% purrr::imap(data_reference_index_rows, pkg = p…
11. base::unlist(., recursive = FALSE)
12. purrr::compact(.)
13. purrr::discard(.x, function(x) is_empty(.f(x)))
14. purrr:::where_if(.x, .p, ...)
15. purrr:::map_(.x, .p, ..., .type = "logical", .purrr_error_call …
16. purrr:::vctrs_vec_compat(.x, .purrr_user_env)
17. purrr::imap(., data_reference_index_rows, pkg = pkg)
18. purrr::map2(.x, vec_index(.x), .f, ...)
19. purrr:::map2_("list", .x, .y, .f, ..., .progress = .progress)
20. purrr:::with_indexed_errors(i = i, names = names, error_call = …
21. base::withCallingHandlers(expr, error = function(cnd) { …
22. purrr:::call_with_cleanup(map2_impl, environment(), .type, .pro…
23. local .f(.x[[i]], .y[[i]], ...)
24. pkgdown:::section_topics(section$contents, pkg$topics, pkg$src_pa…
25. base::rbind(topics, ext_topics(ext_strings))
26. base::rbind(deparse.level, ...)
27. pkgdown:::ext_topics(ext_strings)
28. purrr::map2(pkg, fun, get_rd_from_help)
29. purrr:::map2_("list", .x, .y, .f, ..., .progress = .progress)
30. purrr:::with_indexed_errors(i = i, names = names, error_call = …
31. base::withCallingHandlers(expr, error = function(cnd) { …
32. purrr:::call_with_cleanup(map2_impl, environment(), .type, .pro…
33. local .f(.x[[i]], .y[[i]], ...)
34. rlang::check_installed(package, "as it's used in the reference…
35. base::stop(cnd)
36. (function (cnd) …
37. cli::cli_abort(message, location = i, name = name, pare…
38. | rlang::abort(message, ..., call = call, use_cli_format …
39. | rlang:::signal_abort(cnd, .file)
40. | base::signalCondition(cnd)
41. (function (cnd) …
42. cli::cli_abort(message, location = i, name = name, pare…
43. | rlang::abort(message, ..., call = call, use_cli_format …
44. | rlang:::signal_abort(cnd, .file)
45. | base::signalCondition(cnd)
46. global (function (e) …
```