README.md

rostemplate

Esta librería es 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

Este paquete proporciona una plantilla de pkgdown adaptada a la empleada por la comunidad rOpenSpain, que a su vez es una adaptación de la plantilla Universal creada por Bootstrapius 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
  # No pongas la siguiente línea!
  default_assets: false

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$

Uso de la plantilla

Esta sección detalla diferentes opciones para generar un sitio estático para el paquete deseado con el formato definido por esta plantilla. El resultado de este paso es la generación de un sitio estático compuesto de los archivos html, css, etc. basados en el paquete de R para el que se está generando el sitio.

Con GitHub actions - CI

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

Los flujos de trabajo consisten en archivos con extensión .yaml. La acción rostemplate-docs.yaml crea el sitio estático en la carpeta ./docs mientras que rostemplate-gh-pages.yaml crea el sitio estático en el branch gh-pages.

Para configurar esta opción, es necesario disponer en el repositorio de una carpeta en la ruta .github/workflows y copiar la acción deseada en dicha carpeta.

Alternativa usando las funciones de rostemplate

Aunque el uso del paquete rostemplate en si no es necesario con GitHub actions, se han desarrollado dos funciones que automatizan esta configuración de manera automática. Estas funciones simplemente 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 via r-universe

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

# Deploy to gh-branch

rostemplate::ros_actions_pkgdown_branch()


# Deploy to docs folder
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.yaml

on:
  push:
    paths:
      - '_pkgdown.yaml'

Más información sobre cómo adaptar los triggers de la acción 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() no es más que un alias de pkgdown::build_site(), aportando únicamente 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 de nuestro repositorio (Setting>GitHub Pages), seleccionando el origen deseado (gh-pages, main/docs, etc.).