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.

Introducción

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.

Configuración previa

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

_pkgdown.yml

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:

.Rbuildignore

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

Uso de la plantilla

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.

Con flujos de trabajo de GitHub Actions

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.

Alternativa usando las funciones de rostemplate

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, crean los archivos .Rbuildignore y .github/.gitignore, que ignoran ciertos archivos cuando se compila el paquete:

# 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:

rostemplate-gh-pages.yaml

# 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í.

Generación manual con RStudio

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() es un alias de pkgdown::build_site() que añade un control sobre la configuración del archivo _pkgdown.yml.

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

GitHub Pages

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.).