add more details on how to safeguard docs

booknews.Rmd

@@ -2,6 +2,8 @@
 
 ## dev version
 
+- 2025-07-09, add more details on how to safeguard docs building for rOpenSci packages (#910, `@rmgpanw`)
+
 - 2025-07-09, add a mention of ROR IDs (#909).
 
 - 2025-07-09, remove the upper-case from the NEWS.md template and update the real example link. (#896)

pkg_ci.Rmd

@@ -117,6 +117,24 @@ After transfer to rOpenSci's "ropensci" GitHub organization, each push to the re
 
 After transfer to rOpenSci's "ropensci" GitHub organization, a pkgdown website will be built for your package after each push to the GitHub repo. You can find the status of these builds at `https://ropensci.r-universe.dev/ui#packages` and in the [commit status](https://ropensci.org/blog/2021/09/03/runiverse-docs/#how-it-works). The website build will use your pkgdown config file if you have one, except for the styling that will use the [`rotemplate` package](https://github.com/ropensci-org/rotemplate/). 
 
+If your documentation includes code that relies on, for instance, credentials, here's how to ensure pkgdown docs are rendered in the best possible way.
+
+- For function examples, use the  `examplesIf` roxygen2 tag with the `IN_PKGDOWN` variable e.g. `#' @examplesIf identical(Sys.getenv("IN_PKGDOWN"), "true")`
+- For vignettes, either pre-build if special tools/data/credentials are required which are unavailable on generic build servers (see https://ropensci.org/blog/2019/12/08/precompute-vignettes/), or use the `IN_PKGDOWN` variable with knitr eval option e.g.
+
+```r
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  eval = Sys.getenv("IN_PKGDOWN") == "true"
+)
+```
+
+Examples:
+
+- `examplesIf`:  https://github.com/ropensci/gtexr/blob/592ac781672f07eb67e935d4155570c5960d1fdb/R/get_service_info.R#L14 (see also Docs of the roxygen2 tag: https://roxygen2.r-lib.org/articles/rd.html?q=examplesIf#examples)
+- Vignette, knitr eval option:   https://github.com/ropensci/gtexr/blob/592ac781672f07eb67e935d4155570c5960d1fdb/vignettes/gtexr.Rmd#L16
+
 Please report bugs, questions and feature requests about the central builds and about the template at [https://github.com/ropensci-org/rotemplate/](https://github.com/ropensci-org/rotemplate/).
 
 

pkg_ci.es.Rmd

@@ -133,6 +133,24 @@ Puedes encontrar el estado de este proceso en la URL `https://ropensci.r-univers
 El sitio web estará en `https://docs.ropensci.org/package_name` (por ejemplo [para `magick`](https://docs.ropensci.org/magick)).
 Si tu paquete tiene un archivo de configuración de pkgdown, rOpenSci docs lo usará para crear el sitio web, excepto para el tema, que se utilizará [`rotemplate` paquete](https://github.com/ropensci-org/rotemplate/).
 
+Si tu documentación incluye código que depende, por ejemplo, de credenciales, aquí te explicamos cómo asegurarte de que los documentos pkgdown se representen de la mejor manera posible.
+
+- Para los ejemplos de funciones, utiliza la etiqueta roxygen2 «examplesIf» con la variable «IN_PKGDOWN», por ejemplo, «#' @examplesIf identical(Sys.getenv("IN_PKGDOWN"), "true")».
+- Para viñetas, precompile si se requieren herramientas/datos/credenciales especiales que no están disponibles en servidores de compilación genéricos (consulte https://ropensci.org/blog/2019/12/08/precompute-vignettes/), o utilice la variable `IN_PKGDOWN` con la opción knitr eval, por ejemplo
+
+```r
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  eval = Sys.getenv("IN_PKGDOWN") == "true"
+)
+```
+
+Ejemplos:
+
+- `examplesIf`:https://github.com/ropensci/gtexr/blob/592ac781672f07eb67e935d4155570c5960d1fdb/R/get_service_info.R#L14 (véase también la documentación de la etiqueta roxygen2: https://roxygen2.r-lib.org/articles/rd.html?q=examplesIf#examples)
+- Vignette, opción knitr eval:https://github.com/ropensci/gtexr/blob/592ac781672f07eb67e
+
 Por favor, informa sobre errores, haz preguntas y solicita nuevas funcionalidades sobre este servicio y sobre la plantilla en [https://github.com/ropensci-org/rotemplate/](https://github.com/ropensci-org/rotemplate/).
 
 

pkg_ci.pt.Rmd

@@ -102,6 +102,24 @@ Após a transferência para a organização "ropensci" no GitHub pertencente a r
 
 Após a transferência para a organização "ropensci" no GitHub pertencente a rOpenSci, um site pkgdown será criado para o seu pacote após cada envio para o repositório no GitHub. Você pode encontrar o status dessas compilações em `https://ropensci.r-universe.dev/ui#packages` e na seção [status do commit](https://ropensci.org/blog/2021/09/03/runiverse-docs/#how-it-works). A compilação do site usará seu arquivo config do pkgdown, se você tiver um, exceto para o estilo que usará o pacote [ `rotemplate`](https://github.com/ropensci-org/rotemplate/).
 
+Se sua documentação incluir código que dependa, por exemplo, de credenciais, veja aqui como garantir que os documentos pkgdown sejam renderizados da melhor maneira possível.
+
+- Para exemplos de funções, use a tag roxygen2 `examplesIf` com a variável `IN_PKGDOWN`, por exemplo, `#' @examplesIf identical(Sys.getenv(“IN_PKGDOWN”), “true”)`
+- Para vinhetas, pré-compile se forem necessárias ferramentas/dados/credenciais especiais que não estão disponíveis em servidores de compilação genéricos (consulte https://ropensci.org/blog/2019/12/08/precompute-vignettes/) ou use a variável `IN_PKGDOWN` com a opção knitr eval, por exemplo
+
+```r
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = “#>”,
+  eval = Sys.getenv(“IN_PKGDOWN”) == “true”
+)
+```
+
+Exemplos:
+
+- `examplesIf`:https://github.com/ropensci/gtexr/blob/592ac781672f07eb67e935d4155570c5960d1fdb/R/get_service_info.R#L14 (veja também a documentação da tag roxygen2: https://roxygen2.r-lib.org/articles/rd.html?q=examplesIf#examples)
+- Vignette, opção knitr eval: https://github.com/ropensci/gtexr/blob/592ac781672f07eb67e
+
 Por favor, informe bugs, perguntas e solicitações de recursos sobre as compilações centrais e sobre o modelo em [https://github.com/ropensci-org/rotemplate/](https://github.com/ropensci-org/rotemplate/).