`@examplesIf` `roxygen2` tag support

[rbcavanaugh]

Hi! Trying to convert a package with a pkgdown site to altdoc because it looks great. Converted README.rmd to a .qmd document (which renders just fine on its own). I've tried reinstalling quarto and RStudio and altdoc, restarting RStudio, restarting computer etc. Some kind of quarto path issue perhaps?

library(altdoc)
setup_docs("quarto_website")
render_docs()

returns the following error:

── Update HTML ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Error in `quarto::quarto_render()`:
✖ Error running quarto cli.
ℹ Rerun with `quiet = FALSE` to see the full error message.
Caused by error:
! System command 'quarto' failed
Run `rlang::last_trace()` to see where the error occurred.

Any suggestions? thanks!

acktrace:
     ▆
  1. └─altdoc::render_docs()
  2.   └─altdoc:::.import_settings(...)
  3.     └─altdoc (local) finalize(settings, path, verbose, freeze)
  4.       └─quarto::quarto_render(...)
  5.         └─quarto:::quarto_run(args, echo = TRUE, quarto_bin = quarto_bin)
  6.           └─base::tryCatch(...)
  7.             └─base (local) tryCatchList(expr, classes, parentenv, handlers)
  8.               └─base (local) tryCatchOne(expr, names, parentenv, handlers[[1L]])
  9.                 └─value[[3L]](cond)
 10.                   └─cli::cli_abort(msg, call = .call, parent = e)
 11.                     └─rlang::abort(...)

sessioninfo::session_info()
─ Session info ────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.3.1 (2023-06-16)
 os       macOS Sonoma 14.0
 system   aarch64, darwin20
 ui       RStudio
 language (EN)
 collate  en_US.UTF-8
 ctype    en_US.UTF-8
 tz       America/New_York
 date     2024-04-04
 rstudio  2023.12.1+402 Ocean Storm (desktop)
 pandoc   3.1.1 @ /Applications/RStudio.app/Contents/Resources/app/quarto/bin/tools/ (via rmarkdown)

─ Packages ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 package     * version    date (UTC) lib source
 allofus       1.1.0      2024-04-04 [1] Github (roux-ohdsi/allofus@e56b552)
 altdoc      * 0.3.0.9001 2024-04-04 [1] Github (etiennebacher/altdoc@9640d70)
 cli           3.6.2      2023-12-11 [1] CRAN (R 4.3.1)
 desc          1.4.3      2023-12-10 [1] CRAN (R 4.3.1)
 digest        0.6.35     2024-03-11 [1] CRAN (R 4.3.1)
 dplyr         1.1.4      2023-11-17 [1] CRAN (R 4.3.1)
 evaluate      0.23       2023-11-01 [1] CRAN (R 4.3.1)
 fansi         1.0.6      2023-12-08 [1] CRAN (R 4.3.1)
 fastmap       1.1.1      2023-02-24 [1] CRAN (R 4.3.0)
 fs            1.6.3      2023-07-20 [1] CRAN (R 4.3.0)
 generics      0.1.3      2022-07-05 [1] CRAN (R 4.3.0)
 glue          1.7.0      2024-01-09 [1] CRAN (R 4.3.1)
 htmltools     0.5.8.1    2024-04-04 [1] CRAN (R 4.3.1)
 jsonlite      1.8.8      2023-12-04 [1] CRAN (R 4.3.1)
 knitr         1.45       2023-10-30 [1] CRAN (R 4.3.1)
 later         1.3.2      2023-12-06 [1] CRAN (R 4.3.1)
 lifecycle     1.0.4      2023-11-07 [1] CRAN (R 4.3.1)
 magrittr      2.0.3      2022-03-30 [1] CRAN (R 4.3.0)
 pak           0.7.1      2023-12-11 [1] CRAN (R 4.3.1)
 pillar        1.9.0      2023-03-22 [1] CRAN (R 4.3.0)
 pkgconfig     2.0.3      2019-09-22 [1] CRAN (R 4.3.0)
 processx      3.8.4      2024-03-16 [1] CRAN (R 4.3.1)
 ps            1.7.6      2024-01-18 [1] CRAN (R 4.3.1)
 quarto        1.4        2024-03-06 [1] CRAN (R 4.3.1)
 R6            2.5.1      2021-08-19 [1] CRAN (R 4.3.0)
 Rcpp          1.0.12     2024-01-09 [1] CRAN (R 4.3.1)
 remotes       2.4.2      2021-11-30 [1] CRAN (R 4.3.0)
 rlang         1.1.3      2024-01-10 [1] CRAN (R 4.3.1)
 rmarkdown     2.26       2024-03-05 [1] CRAN (R 4.3.1)
 rstudioapi    0.16.0     2024-03-24 [1] CRAN (R 4.3.1)
 sessioninfo   1.2.2      2021-12-06 [1] CRAN (R 4.3.0)
 tibble        3.2.1      2023-03-20 [1] CRAN (R 4.3.0)
 tidyselect    1.2.1      2024-03-11 [1] CRAN (R 4.3.1)
 utf8          1.2.4      2023-10-22 [1] CRAN (R 4.3.1)
 vctrs         0.6.5      2023-12-01 [1] CRAN (R 4.3.1)
 xfun          0.43       2024-03-25 [1] CRAN (R 4.3.1)
 yaml          2.3.8      2023-12-11 [1] CRAN (R 4.3.1)

 [1] /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/library

[vincentarelbundock]

Hi @rbcavanaugh

Does your README have a YAML preamble? What happens if you remove it?

It's a bit hard to diagnose without just with that. Is there a Github repo I can look at?

[rbcavanaugh]

No preamble. Does this help? I pushed a branch where I'm getting the error here: https://github.com/roux-ohdsi/allofus/tree/test-altdoc

[vincentarelbundock]

When I run render_docs(verbose=TRUE), I see this error in rendering one of your vignettes. It does not seem altdoc-related:

processing file: aou_create_temp_table.qmd
1/3                  
2/3 [unnamed-chunk-1]

Quitting from lines 65-83 [unnamed-chunk-1] (aou_create_temp_table.qmd)
Error:
! Unable to connect to CDR
Backtrace:
 1. allofus::aou_connect()
 2. base::tryCatch(...)
 3. base (local) tryCatchList(expr, classes, parentenv, handlers)
 4. base (local) tryCatchOne(expr, names, parentenv, handlers[[1L]])
 5. value[[3L]](cond)
Execution halted
Error in `quarto::quarto_render()` at altdoc/R/settings_quarto_website.R:38:5:
✖ Error running quarto cli.
Caused by error:
! System command 'quarto' failed

@etiennebacher & @kylebutts do you think we should make verbose=TRUE by default. My guess is that this kind of thing will happen all the time.

[etiennebacher]

@etiennebacher & @kylebutts do you think we should make verbose=TRUE by default. My guess is that this kind of thing will happen all the time.

I think we should show error messages all the time, no matter the value of verbose. However, if everything works fine I don't see the need to clutter the console with all those quarto rendering messages, so I don't think setting verbose = TRUE as default is the solution. I can try to take a look this weekend to see how hard it would be to only show the error messages without all the other noise

[vincentarelbundock]

Right. Those messages are only available when quarto is super verbose. My assumption was that this is going to be annoying to capture and that, as a team, we don't have time to invest for something trivial like that. But sure, if you feel like it, it would be great to have a smart function that can figure out how to tell what is noise and what is useful error.

[etiennebacher]

as a team, we don't have time to invest for something trivial like that

True, but I can also see in the polars CI that it's super annoying to go through tons of useless messages just to find the one error message that is actually useful. Extreme example given the number of man pages in polars of course, but I can imagine it's the same if you have 20+ functions.

But I won't lose days on this for sure, I'm just curious how hard it would be.

[vincentarelbundock]

If you can't figure it out, rpolars can always set verbose=FALSE

[rbcavanaugh]

Thanks @vincentarelbundock - is that file the .qmd file generated for the function reference (e.g., what would be the reference page in a pkg down website for the function?.

Only a few of the package functions will work outside of the specialized compute environment the package is intended for, so the examples are run conditionally if this environment is detected.

# returns TRUE if the environment is detected. 
on_workbench <- function() {
  detect_specialized_compute_environment() 
}

and the roxygen2 comments look like this:

#' @examplesIf on_workbench()
#' # do example stuff
#' con <- aou_connect()
#' df <- data.frame(
#'   ...

is it possible that pkg down evaluates this on_workbench() function, altdoc does not? (or that pkgdown doesn't evaluate examples at all?).

Here's the current pkgdown page for that function: https://roux-ohdsi.github.io/allofus/reference/aou_create_temp_table.html

Anyways...perhaps this is our issue and not yours. thanks for looking into it.

[vincentarelbundock]

@rbcavanaugh you got it! Exactly right. The problem is that we don't support @examplesIf properly.

I just put together a proof of concept patch, which adds support. The pull request is here: https://github.com/etiennebacher/altdoc/pull/271

FWIW, the allofus docs looks pretty great on my computer when I build it with the patched version of altdoc.

You can try it by first restarting R completely, then:

library(remotes)
install_github(repo="etiennebacher/altdoc", ref = github_pull(271))

library(altdoc)
render_docs(verbose = TRUE)

[rbcavanaugh]

wow fantastic - thanks that works perfectly. I get the hesitation with the 'work around' on detecting the @examplesIf tag though.

I've got some work to do to incorporate some customizations we have from pkgdown (we have a few 'web only' vignettes that aren't built with the R package and I need to group the functions so that they line up with a pending manuscript) but this definitely looks like an upgrade.

[vincentarelbundock]

Great! Let me know if you run into other issues.

[etiennebacher]

Closed by #271