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.
El diseño original de las plantillas que componen pkgdown es bastante rígido, en el sentido de que ligeras modificaciones (como el tipo de navbar o la localización del footer) pueden provocar que el renderizado final no sea óptimo. Para solucionarlo se han empleado algunos hacks en el fichero css y pequeños fragmentos en javascript.
Otra limitación es la diferencia de versiones Bootstrap, ya que esta plantilla pkgdown emplea la versión Bootstrap 5 mientras que Universal emplea la 3.3.7.
En la raíz del proyecto ha de existir un archivo _pkgdown.yml con al menos las siguientes líneas:
template:
package: rostemplate
# No pongas la siguiente línea!
default_assets: falsePuedes 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$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.
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.
rostemplateAunque 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í.
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.
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.).