---
title: "Uso del paquete rdst"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Uso del paquete rdst}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>"
)
```

## Instalacion

```r
# Desde R-universe (recomendado)
install.packages("rdst", repos = "https://<tu-usuario>.r-universe.dev")

# Desde GitLab
remotes::install_gitlab("tjma-community/public/templates/rdst")
```

## Crear un proyecto nuevo

La funcion principal es `create_project()`. Con una sola llamada genera
la estructura completa del proyecto, inicializa renv y hace el primer
commit de git.

```r
library(rdst)

create_project(
  path        = "~/proyectos/mi_analisis",
  author      = "Tu Nombre",
  gitlab_user = "tu_usuario"
)
```

El proyecto se crea con esta estructura:

```
mi_analisis/
├── _targets.R          # pipeline de analisis
├── _quarto.yml         # configuracion de publicacion
├── index.qmd           # documento principal
├── renv.lock           # snapshot de paquetes
├── .gitlab-ci.yml      # CI/CD: render + GitLab Pages
├── R/
│   ├── config.R        # opciones globales del proyecto
│   ├── bibliography.R  # bibliografia de paquetes
│   └── utils.R         # funciones auxiliares
├── setup/
│   ├── bootstrap.R         # arranque del entorno R
│   └── install_sysdeps.sh  # dependencias del sistema (Linux)
├── data/
│   ├── raw/            # datos originales (.gitignore)
│   └── processed/      # datos procesados (.gitignore)
├── outputs/            # figuras y tablas (.gitignore)
└── references/         # bibliografía .bib
```

## Argumentos de `create_project()`

| Argumento | Por defecto | Descripcion |
|---|---|---|
| `path` | — | Ruta del nuevo proyecto. El ultimo componente es el nombre. |
| `author` | opcion `usethis.full_name` o `$USER` | Nombre del autor para el YAML. |
| `gitlab_user` | variable `$GITLAB_USER` | Usuario de GitLab para CI y URL de Pages. |
| `r_version` | Version actual de R | Version minima de R declarada en `bootstrap.R`. |
| `lang` | `"es"` | Idioma de las plantillas: `"es"` o `"en"`. |
| `use_renv` | `TRUE` | Inicializar renv en el proyecto. |
| `use_targets` | `TRUE` | Crear `_targets.R`. |
| `use_ci` | `TRUE` | Crear `.gitlab-ci.yml`. |
| `open` | `TRUE` (interactivo) | Abrir el proyecto tras la creacion. |

## Primer uso en una maquina nueva

Una vez creado el proyecto y dentro de el:

```bash
# 1. Instalar dependencias del sistema (Linux)
bash setup/install_sysdeps.sh
```

```r
# 2. Restaurar los paquetes R exactos del renv.lock
source("setup/bootstrap.R")
```

```r
# 3. Ejecutar el pipeline
targets::tar_make()
```

```r
# 4. Renderizar el documento
quarto::quarto_render("index.qmd")
```

```bash
# 5. Publicar — GitLab CI gestiona el render y el despliegue
git push
```

## Flujo de trabajo habitual

```r
# Ver que targets necesitan re-ejecutarse
targets::tar_outdated()

# Re-ejecutar el pipeline (solo lo que ha cambiado)
targets::tar_make()

# Ver el grafo de dependencias
targets::tar_visnetwork()

# Anadir un paquete nuevo
renv::install("nuevo_paquete")
renv::snapshot()  # actualizar renv.lock
```

## Proyectos en ingles

El argumento `lang` genera las plantillas en el idioma seleccionado.
Los comentarios del codigo, el README y los mensajes de configuracion
se generan en ese idioma:

```r
create_project(
  path        = "~/projects/my_analysis",
  author      = "Your Name",
  gitlab_user = "your_user",
  lang        = "en"
)
```

## Publicacion en GitLab Pages

El fichero `.gitlab-ci.yml` generado automatiza todo el proceso en
cada `git push` a la rama principal:

1. Restaura el entorno R desde `renv.lock`
2. Ejecuta `targets::tar_make()`
3. Renderiza `index.qmd` con Quarto
4. Despliega el resultado en GitLab Pages

La URL del sitio publicado es:

```
https://<gitlab_user>.gitlab.io/<project_name>
```
