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

Wed Jan 3 19:48:03 CET 2024

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> 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> 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> 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 mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>>
>
>
> --
> http://hadley.nz
>
>
>

-- 
http://hadley.nz

	[[alternative HTML version deleted]]