rostemplate

Este paquete proporciona una plantilla pkgdown adaptada al sitio web de rOpenSpain.

Esta plantilla es privada y de uso exclusivo para los paquetes de rOpenSpain. No la uses para otros paquetes.

La plantilla de pkgdown se basa en la que emplea la comunidad rOpenSpain, que a su vez es una adaptación de la plantilla Universal creada por DevCows con la variación de color violet.

En la raíz del proyecto debe existir un archivo _pkgdown.yml con al menos las siguientes líneas:

template:
  bootstrap: 5
  package: rostemplate

Puedes encontrar información sobre cómo configurar otras opciones en _pkgdown.yml aquí.

Además, es necesario añadir al archivo .Rbuildignore las siguientes líneas:

^\.github$
^docs$
^_pkgdown\.yml$
^_pkgdown\.yaml$

Esta sección detalla diferentes opciones para generar un sitio pkgdown con el formato definido por esta plantilla. El resultado es un sitio estático compuesto por archivos HTML, CSS y otros recursos basados en el paquete de R correspondiente.

GitHub Actions permite automatizar procesos cuando se activa un evento. En este caso se han preparado dos flujos de trabajo que actualizan el sitio pkgdown cada vez que se añade un commit al repositorio.

Los flujos de trabajo son archivos con extensión .yaml. El flujo rostemplate-docs.yaml crea el sitio pkgdown en la carpeta ./docs, mientras que rostemplate-gh-pages.yaml crea el sitio pkgdown en la rama gh-pages.

Para configurar esta opción, crea la carpeta .github/workflows en el repositorio y copia en ella el flujo de trabajo deseado.

Aunque el uso del paquete rostemplate no es necesario con GitHub Actions, se han desarrollado dos funciones que automatizan esta configuración. Estas funciones crean el directorio .github/workflows si no existe y copian los archivos solicitados en la ruta correspondiente. Además, actualizan .Rbuildignore y .github/.gitignore para excluir los archivos generados de la compilación del paquete y del control de versiones:

# Instalación vía r-universe
install.packages(
  "rostemplate",
  repos = c("https://ropenspain.r-universe.dev", "https://cloud.r-project.org")
)

# O usando pak.
pak::pak("ropenspain/rostemplate")

# Publicar en la rama gh-pages
rostemplate::ros_actions_pkgdown_branch()

# Publicar en la carpeta docs
rostemplate::ros_actions_pkgdown_docs()

Es posible cambiar el evento que desencadena la actualización del sitio:

# Actualiza en cada commit - por defecto
on:
  push:
    branches:
      - main
      - master

# Actualiza cuando se modifica un archivo específico: _pkgdown.yml
on:
  push:
    paths:
      - '_pkgdown.yml'

Más información sobre cómo adaptar los eventos del flujo de trabajo aquí.

El sitio estático se puede generar igualmente desde una sesión local en RStudio. Para ello, es necesario instalar este paquete:

install.packages(
  "rostemplate",
  repos = c("https://ropenspain.r-universe.dev", "https://cloud.r-project.org")
)

Una vez instalado, debes ejecutar este código:

rostemplate::ros_build()

La función rostemplate::ros_build() envuelve pkgdown::build_site() y pide confirmar la configuración de _pkgdown.yml antes de generar el sitio.

Una vez generado el sitio, es necesario actualizar el repositorio remoto en GitHub mediante un commit y un push.

Una vez generado el sitio estático y subido al repositorio en GitHub, el último paso es activar el sitio web a través de los Settings del repositorio (Settings > GitHub Pages) y seleccionar el origen deseado (gh-pages, main/docs, etc.).