[R-pkg-devel] how to use pkgdown::build_site() with a project using S7 with a specialized plot()?
Daniel Kelley
ke||ey @end|ng |rom d@|@c@
Wed Jan 3 20:18:05 CET 2024
Oh, Hadley, I'm sorry to bother you whilst you're on vacation. Please don't take too much time on. I'm certainly not in a rush at all.
To answer your question, yes, I rebuilt the documentation (within RStudio, via the 'More/Document' scheme) and it still fails.
I wonder if I need to do a
method(plot, mooring:::mooringS7) <- function(ETC) {ETC}
instead of
`plot.mooring::mooring` <- function(ETC) {ETC}
which is what I'm doing now, and which works for plotting but not webpage-building.
PS. That `mooringS7` vs `mooring` name difference is because I am using
mooringS7 <- S7::new_class("mooring", ETC
because I want the user-facing function to be called `mooring`. (I am having the user using the object constructor directly. I guess I could, but I'm doing it this way to retain my old code, which used S3 methodology and had a fair bit of logic before constructing a return value. I can change that, of course. For now, my S7 steps are a bit timid, so I can fall back to my S3 code if I cannot figure things out.)
On Jan 3, 2024, at 2:48 PM, Hadley Wickham <h.wickham using gmail.com> wrote:
CAUTION: The Sender of this email is not from within Dalhousie.
Did you re-document? You’ll need that to correctly regenerate the .Rd, I think. (Sorry I’m on vacation so I’m guessing at stuff from my phone)
Hadley
On Thursday, January 4, 2024, Daniel Kelley <kelley using dal.ca<mailto:kelley using dal.ca>> wrote:
Thanks. I installed the latest roxygen2 and pkgdown, and tried to make a simple reprex
git clone https://github.com/dankelley/mooring.git
cd mooring
git checkout S7
Rscript -e "pkgdown::clean_site()"
Rscript -e "pkgdown::build_site()"
but it still fails. (Full output is below, for completeness.) I wonder whether I ought to be doing something extra in the Roxygen code (in file R/plot.R within this directory.). Please note that I can rename it as "draw()" or something, but I'm hoping to learn S7 properly, because I'm really quite keen to leave my S3 and S4 days behind me. (PS to Hadley: I loved the presentation you gave on what was then R7, and have recommended it to colleagues not just for the R7 information, but for the concise explanation of the benefit of OOP and generics.)
── Installing package mooring into temporary library ───────────────────────────
── Building pkgdown site for package mooring ───────────────────────────────────
Reading from: /Users/kelley/wednesday/mooring
Writing to: /Users/kelley/wednesday/mooring/docs
── Initialising site ───────────────────────────────────────────────────────────
Copying
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/bootstrap-toc.css,
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/bootstrap-toc.js,
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/docsearch.css,
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/docsearch.js,
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/link.svg,
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/pkgdown.css,
and
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/pkgdown.js
to bootstrap-toc.css, bootstrap-toc.js, docsearch.css, docsearch.js, link.svg,
pkgdown.css, and pkgdown.js
── Building home ───────────────────────────────────────────────────────────────
Writing authors.html
Copying man/figures/Makefile, man/figures/README-example-1.png,
man/figures/README-example-2.png, man/figures/force_diagram.R, and
man/figures/force_diagram.png
to reference/figures/Makefile, reference/figures/README-example-1.png,
reference/figures/README-example-2.png, reference/figures/force_diagram.R, and
reference/figures/force_diagram.png
Writing 404.html
── Building function reference ─────────────────────────────────────────────────
Error:
! in callr subprocess.
Caused by error in `map2(.x, vec_index(.x), .f, ...)`:
! In index: 1.
---
Standard error:
── Building pkgdown site for package mooring ───────────────────────────────────
Reading from: /Users/kelley/wednesday/mooring
Writing to: /Users/kelley/wednesday/mooring/docs
── Initialising site ───────────────────────────────────────────────────────────
Copying
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/bootstrap-toc.css,
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/bootstrap-toc.js,
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/docsearch.css,
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/docsearch.js,
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/link.svg,
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/pkgdown.css,
and
../../../../Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library/pkgdown/BS3/assets/pkgdown.js
to bootstrap-toc.css, bootstrap-toc.js, docsearch.css, docsearch.js, link.svg,
pkgdown.css, and pkgdown.js
── Building home ───────────────────────────────────────────────────────────────
Writing authors.html
Copying man/figures/Makefile, man/figures/README-example-1.png,
man/figures/README-example-2.png, man/figures/force_diagram.R, and
man/figures/force_diagram.png
to reference/figures/Makefile, reference/figures/README-example-1.png,
reference/figures/README-example-2.png, reference/figures/force_diagram.R, and
reference/figures/force_diagram.png
Writing 404.html
── Building function reference ─────────────────────────────────────────────────
---
Backtrace:
1. pkgdown::build_site()
2. pkgdown:::build_site_external(pkg = pkg, examples = examples, run_dont_run = run_don…
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_msg(remerr[[3]]))
---
Subprocess backtrace:
1. pkgdown::build_site(...)
2. pkgdown:::build_site_local(pkg = pkg, examples = examples, run_dont_run = run_dont_r…
3. pkgdown::build_reference(pkg, lazy = lazy, examples = examples, run_dont_run = run_…
4. pkgdown::build_reference_index(pkg)
5. pkgdown::render_page(pkg, "reference-index", data = data_reference_index(pkg), …
6. pkgdown:::render_page_html(pkg, name = name, data = data, depth = depth)
7. utils::modifyList(data_template(pkg, depth = depth), data)
8. base::stopifnot(is.list(x), is.list(val))
9. pkgdown:::data_reference_index(pkg)
10. meta %>% purrr::imap(data_reference_index_rows, pkg = pkg) %>% …
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 = .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 = .purrr_error_call, …
21. base::withCallingHandlers(expr, error = function(cnd) { …
22. purrr:::call_with_cleanup(map2_impl, environment(), .type, .progress, …
23. local .f(.x[[i]], .y[[i]], ...)
24. pkgdown:::section_topics(section$contents, pkg$topics, pkg$src_path)
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 = .purrr_error_call, …
31. base::withCallingHandlers(expr, error = function(cnd) { …
32. purrr:::call_with_cleanup(map2_impl, environment(), .type, .progress, …
33. local .f(.x[[i]], .y[[i]], ...)
34. rlang::check_installed(package, "as it's used in the reference index.")
35. base::stop(cnd)
36. (function (cnd) …
37. cli::cli_abort(message, location = i, name = name, parent = cnd, …
38. | rlang::abort(message, ..., call = call, use_cli_format = TRUE, …
39. | rlang:::signal_abort(cnd, .file)
40. | base::signalCondition(cnd)
41. (function (cnd) …
42. cli::cli_abort(message, location = i, name = name, parent = cnd, …
43. | rlang::abort(message, ..., call = call, use_cli_format = TRUE, …
44. | rlang:::signal_abort(cnd, .file)
45. | base::signalCondition(cnd)
46. global (function (e) …
Execution halted
On Jan 3, 2024, at 1:06 PM, Hadley Wickham <h.wickham using gmail.com<mailto:h.wickham using gmail.com>> wrote:
CAUTION: The Sender of this email is not from within Dalhousie.
This bug is fixed in the dev version (I don’t remember off the top of my head in which of pkgdown and roxygen2 you need but it might be both). I’m planning CRAN updates for both in the near future.
Hadley
On Thursday, January 4, 2024, Daniel Kelley <kelley using dal.ca<mailto:kelley using dal.ca>> wrote:
# 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) …
```
______________________________________________
R-package-devel using r-project.org<mailto:R-package-devel using r-project.org> mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
--
http://hadley.nz<http://hadley.nz/>
--
http://hadley.nz<http://hadley.nz/>
[[alternative HTML version deleted]]
More information about the R-package-devel
mailing list