-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
171 lines (127 loc) · 5.54 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
tidy = "styler",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# rostemplate <img src="man/figures/logo.png" align="right" width="120"/>
<!-- badges: start -->
[](https://ropenspain.es/)
[](https://ropenspain.r-universe.dev/rostemplate)
[](https://github.com/ropenspain/rostemplate/actions)
[](https://app.codecov.io/gh/ropenspain/rostemplate)
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->
Esta librería es una plantilla **pkgdown** adaptada al sitio web de
[rOpenSpain](https://ropenspain.es/).
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](https://ropenspain.es/), que a su vez es una
adaptación de la plantilla
[Universal](https://bootstrapious.com/p/universal-business-e-commerce-template)
creada por
[Bootstrapius](https://bootstrapious.com/p/universal-business-e-commerce-template)
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:
``` yaml
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í](https://pkgdown.r-lib.org/articles/pkgdown.html).
Adicionalmente, es necesario añadir al archivo `.Rbuildignore` las siguientes
líneas:
``` default
^\.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](https://github.com/ropenspain/rostemplate/blob/main/inst/yaml/rostemplate-docs.yaml)
crea el sitio estático en la carpeta `./docs` mientras que
[rostemplate-gh-pages.yaml](https://github.com/ropenspain/rostemplate/blob/main/inst/yaml/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:
```{r eval=FALSE}
# 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:
``` yaml
# 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í](https://docs.github.com/es/free-pro-team@latest/actions/reference/events-that-trigger-workflows).
### RStudio - manual
El sitio estático se puede generar igualmente desde una sesión local en
**RStudio**. Para ello, es necesario instalar este paquete:
```{r eval=FALSE}
install.packages("rostemplate",
repos = c("https://ropenspain.r-universe.dev", "https://cloud.r-project.org")
)
```
Una vez instalado, se ha de ejecutar este script:
```{r eval=FALSE}
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.).