Módulo 7: La versatilidad de Quarto

Mauricio Moreno, PhD

Antes de comenzar…

  • En este módulo final, veremos superficialmente el uso de la plataforma Github.

  • El ambiente de Github puede llegar a ser abrumador por la cantidad de opciones y funcionalidades.

  • El objetivo de este curso es que los estudiantes entiendan su funcionamiento más básico en cuanto a su relación con la creación de reportes de Quarto, por lo tanto, entre los diversos temas que no son cubiertos aquí, puedo enlistar los siguientes:

    • Control de versiones en Github (branches)

    • Manejo de grupos de colaboración

    • Comandos de Git

    • Creación de librerías de R

Introducción

  • Quarto fue lanzado en el 2022.

  • Como tal, es un software bastante reciente y aún no existen manuales completos acerca de su uso (si has usado rmarkdown la curva de aprendizaje es particularmente sencilla).

  • Sin embargo, no es difícil encontrar una considerable cantidad de material creado tanto por POSIT (la empresa responsable de su desarrollo) como por usuarios particulares.

  • En ambos casos, la mejor manera de aprender sus usos (al menos hasta el momento), es explorando el código fuente de documentos disponibles en el internet hechos en Quarto.

  • ¿En donde encontramos estos códigos fuente?

  • Github

Introducción a Github

Introducción a Github

  • Github es una plataforma para desarrolladores de software que ofrece las funcionalidades de almacenar, manejar y compartir código.

  • Se basa en el uso del software Git.

  • Instalar Git y configurar su uso con RStudio y una cuenta de Github es un proceso relativamente sencillo. Así que iremos paso por paso.

  • Por el momento cierra RStudio.

Paso 1: Creando una cuenta de Github

  • Entra a la página web de Github: https://github.com/

  • Click en Sign up:

    • Ingresamos nuestro correo electrónico

    • Creamos una contraseña

    • Creamos un nombre de usuario

  • Luego nos pedirá autentificar nuestra cuenta (resolver un reto).

  • Recibirás un código al correo que utilizaste para verificar tu cuenta.

  • Ya verificada la cuenta, podemos saltarnos la personalización.

  • ¡Listo!

Paso 2: Instala Git

  • Entra a la página web de Git: https://git-scm.com/

  • Click en Downloads

  • Escoge tu sistema operativo y tipo de procesador (la última versión de R solo es compatible con computadores 64 bit).

  • Descarga y ejecuta el archivo .exe (Git-2.44.0-64-bit.exe)

  • Sigue el menú de instalación SIN cambiar las opciones predeterminadas

Paso 3: Verifica que Git se instaló

  • Para verificar, abre Rstudio y sigue Tools > Global Options > Git/SVN

Paso 4: Pero, ¿funciona?

  • Vamos a clonar un repositorio de Github creando un proyecto

  • Para ello, escogemos la opción de Version Control

Paso 4: Pero, ¿funciona?

  • Escogemos la opción Git

Paso 4: Pero, ¿funciona?

  • En el URL vamos a pegar este URL: https://github.com/mmorenozam/plantilla-tesis

  • Escogemos la ubicación en nuestro computador y hacemos click en Create Project y ¡listo!

Hasta el momento…

  • Hemos (espero) creado exitosamente una cuenta en Github e instalado Git en nuestros computadores.

  • Tenemos la posibilidad de clonar repositorios existentes.

  • Sin embargo, estamos solo a medio camino de explotar un poco más las ventajas de Github (no podemos aún crear, manejar y empujar nuestros propios proyectos en Github).

  • Para esto, nos falta vincular nuestra cuenta de Github con RStudio.

  • Sin embargo, haremos una pausa para ver el repositorio que hemos clonado.

Escribiendo una tesis de grado en Quarto

  • El repositorio que acabamos de clonar, contiene un template para llevar a cabo una tesis de grado.

  • Realicé este template en base de la extensión quarto-thesis de autoría de Eli Holmes.

  • Usando este template ya seremos capaces de redactar una tesis con:

    • los nombres de sección traducidos al español

    • bibliografía en formato APA

    • índice, listas de figuras, listas de tablas, abreviaciones etc, generadas automáticamente en Quarto.

  • Usa las funcionalidades de \(\LaTeX{}\) para generar formatos elegantes y agradables a la vista, así como su muy eficiente indexación.

  • Requisitos:

    • Quarto version 1.3.450 (Llas más recientes contienen “bugs” que evitan una renderización adecuada).

    • Tinytex

    • (Idealmente) un mínimo conocimiento de edición de texto en \(\LaTeX{}\)

    • (Opcional) Zotero para manejo de referencias bibliográficas

Manejo de Bibliografía

  • En general, para hacer uso de referencias bibliográficas, Quarto utiliza biblatex o biber que son paquetes de \(\LaTeX{}\).

  • Estos se basan en archivos de extensión .bib donde las referencias son almacenadas en lenguage \(\TeX{}\).

  • Para mantener nuestra “biblioteca” bien podemos usar un editor de texto y modificar manualmente nuestro archivo .bib o

  • Hacer uso de algún software que nos ayude a manejar nuestras colecciones de referencias.

  • Entre estos, Zotero es recomendado ya que tiene conexión automática con el editor visual de Quarto.

  • Sin embargo, en esta plantilla en particular, debemos explícitamente contar con un archivo .bib, por lo que bien podrías usar otro software capaz de generarlo (Mendeley por ejemplo).

  • Independientemente del software con el que manejes tus citas, el único requisito para usarlo con esta plantilla, es que sea capaz de generar archivos .bib.

¡Manos a la Obra!

Vinculando Github con RStudio

  • Retomando, hasta el momento hemos instalado y configurado lo necesario tan solo para clonar repositorios.

  • En el pasado, vincular Github con RStudio requería el ingresar comandos en el Terminal para configurar Git.

  • Afortunadamente, hoy por hoy podemos hacer uso de librerías que nos facilitan el proceso desde la consola de RStudio.

  • Para esto, comenzamos instalando las librerías: install.packages(c("usethis", "gitcreds", "oskeyring")).

Paso 1: Creando credenciales

  • Ahora, lo primero que haremos es configurar Git para que sepa la cuenta a vincular.

  • Reiniciamos RStudio y pegamos el siguiente comando en la consola:

usethis::use_git_config(user.name = "TuNombreDeUsuario", user.email = "[email protected]")
  • El siguiente paso es crear un token personal:
usethis::create_github_token()
  • Este comando abrirá una página en tu navegador para que ingreses a Github con la cuenta que creaste

Paso 1: Vinculando Github con RStudio

  • Una vez que ingreses a tu cuenta, directamente te aparecerá la opción de crear un token:
  • Puedes escoger el tiempo de expiración del mismo
  • Click en Generate token

Paso 1: Vinculando Github con RStudio

  • Tu token se mostrará en la pantalla con la opción de copiarlo

  • Esta es la UNICA vez que tendrás el chance de verlo.

  • Cópialo por el momento en un block de notas.

  • Si no lo copias en esta única oportunidad, tendrás que generar otro.

Paso 2: Creando el vínculo

  • Ahora que tienes tu token a salvo, es momento de vincular RStudio a tu cuenta de Github
gitcreds::gitcreds_set()
  • Si es la primera vez que estás vinculando Github con RStudio, te aparecerá lo siguiente:

  • Pega tu token y enter.

Paso 3: Pero, ¿funciona?

  • Reinicia R una vez más y ejecuta en la consola:
usethis::gh_token_help()
  • Deberá aparecerte algo similar a esto:

Empujando nuestro primer repositorio

  • La mejor manera de comprobar que el vínculo/conexión entre tu RStudio y tu cuenta de Github, es “empujando” un repositorio en tu cuenta de Github.

  • En resumen, lo que haremos es crear manualmente un repositorio vacío en Github y luego lo “poblaremos” con un projecto de RStudio (específicamente uno de Quarto).

  • Para esto, puedes utilizar el repositorio con el template de la tesis que anteriormente clonamos (desde el paso 3) o hacerlo siguiendo los pasos desde el principio que mostraré a continuación.

Paso 1: Creando un repositorio vacío en Github

  • En tu cuenta de Github: Click en la foto de tu avatar > Your repositories > New. Deberás llegar a una vista como la siguiente:

Paso 1: Creando un repositorio vacío en Github

  • Una vez que le hayas dado un nombre a tu nuevo repositorio y dado click en Create repository, verás algo como:

Paso 2: Creando un proyecto para empujar

  • De vuelta en RStudio, crearemos un proyecto de Quarto

  • Asegúrate que la opción de Create a git repository esté marcada

Paso 3: Empujando un proyecto a Github por primera vez

  • Una vez creado el proyecto, tenemos dos opciones para empujar nuestro repositorio:

    • Usando únicamente el terminal

    • Usando la GUI de RStudio y el terminal

  • En ambas opciones la lógica es “add/stage” los cambios, “commit”, definir el origen y “push” (empujar).

Paso 3.1: Empujando desde el terminal

  • En el terminal empezaremos ingresando los siguientes comandos
git add .
git commit -m "un comentario"
  • De vuelta en el repositorio vacío que creamos, copia los comandos indicados abajo y pégalos de vuelta en el terminal de R:

Paso 3.1: Empujando desde el terminal

  • Si todo salió bien, verás en el terminal algo como:

Paso 3.2: Empujando con la GUI y el terminal

  • En la GUI de RStudio, puedes notar que en la ventana del ambiente tienes las siguientes opciones:

  • El procedimiento a seguir aquí es: click en Commit>Seleccionar todos los archivos en la ventana que se abre>Stage>Añadir un comentario>Commit.

  • Esto es equivalente a los comandos git add . y git commit -m "un comentario" que usamos anteriormente.

  • De aquí, copiamos los comandos del repositorio vacío que anteriormente creamos, y los pegamos en la terminal.

Paso 4: ¡Nuestro repositorio está listo!

  • Cualquiera haya sido tu opción de empujar, una vez que refresques el navegador el repositorio que creaste ya no estará vacío, y verás algo como:

Actualizando nuestro repositorio

  • El procedimiento que acabamos de ver es necesario únicamente para la primera vez que empujamos al repositorio.

  • Es decir, ya no necesitamos llevar a cabo la conexión entre nuestro repositorio local y el de Github.

  • Basta entonces usar de aquí en adelante la GUI de RStudio, o comandos en la terminal.

  • Para usar la GUI, al procedimiento anterior, lo terminamos haciendo click en Push (en la ventana de ambiente de Git).

  • Para usar la terminal, cada vez que desees actualizar tu repositorio en Github, puedes usar estos comandos directamente en la terminal:

git add .
git commit -m "un comentario"
git push

Nuestra primera página web con Quarto

  • Cómo te habrás dado cuenta, lo (quizás) más difícil hasta el momento ha sido el vincular correctamente Github con RStudio y Git.

  • Una vez que lo hemos hecho, vamos a crear nuestra primera página web usando Quarto.

  • Vamos a dirigirnos a File > New Project… > New directory > Quarto Website > Asignamos el lugar de nuestro repositorio localmente, marcamos la opción de Create a Git repository > Create project

  • En tu nuevo proyecto, notarás en la ventana de Files de RStudio se ha creado un archivo de nombre _quarto.yml. Este archivo contiene las instrucciones de tu proyecto. Lo único que haremos en este es añadir la línea output-dir: docs debajo de type: website de la siguiente manera:

project:
  type: website
  output-dir: docs

Ahora, copiaremos la presentación que usamos de ejemplo al final del módulo 6 en el documento de Quarto de este proyecto y renderizamos.

Nuestra primera página web con Quarto

  • Ahora, crearemos un repositorio vacío en nuestro Github y empujaremos dentro de este nuestro proyecto recientemente creado.

  • Para poner en línea nuestra página web con esta pequeña presentación, nos dirigimos ahora a Github a este repositorio ya poblado y seguimos Settings > Pages (en el menú a la izquierda de nuestra pantalla) > Branch > Elegimos master (o main) y la opcion de /docs que está alado > Save

  • ¡Listo!, en unos minutos nuestra primera página web estará en línea

  • Mientras esperamos, unos comentarios:

    • Github (así como otros servidores), sólamente permiten el alojamiento de páginas web estáticas.

    • Github tiene un almacenamiento máximo de tus proyectos de hasta 100 MB. Pasado este límite, necesitas abrir un plan de pagos.

    • Sin plan de pagos, todo lo que subas conjuntamente con tu proyecto, es abierto a todo el público. Si los datos de tu proyecto son confidenciales o sensibles, puedes especificar a Git que y que no debe subir usando el archivo .gitgnore que se crea en todo proyecto vinculado a un repositorio. Un poco más de información aquí.

¡Gracias!