rostemplate

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

Esta plantilla es una plantilla privada para uso exclusivo de los paquetes de rOpenSpain. Por favor, no la uses para otros paquetes.

Introducción

La plantilla de pkgdown está adaptada a la empleada por 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 ha de 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í.

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

^\.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 workflows de GitHub Actions

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

Los workflows son archivos con extensión .yaml. El workflow 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, es necesario disponer en el repositorio de una carpeta en la ruta .github/workflows y copiar el workflow deseado en dicha carpeta.

Alternativa usando las funciones de rostemplate

Aunque el uso del paquete rostemplate en sí 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 existiera previamente y copian los archivos solicitados en la ruta correspondiente. Adicionalmente, 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:

# 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 triggers del workflow aquí.

RStudio - manual

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, se ha de ejecutar este script:

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