4 Reportes con Quarto

Fecha de publicación

26 de agosto de 2024

4.1 ¿Qué es Quarto y como funciona?

Quarto es un sistema de generación de informes dinámicos basados en Markdown.

Si usas una versión de Rstudio superior a la v2022.07.1, entonces ya tienes Quarto instalado.
Si usas VSCode u otro editor, entonces necesitas ir primero a la página https://quarto.org/docs/get-started/ y bajar la última versión. Además debes instalar la extensión de Quarto (https://marketplace.visualstudio.com/items?itemName=quarto.quarto).

El flujo que sigue Quarto es el siguiente:

graph LR;
    qmd["<span style='color:#0096D6'><i class='fa-regular fa-file'></i> qmd</span>"]
    Jupyter["<span style='color:#AA007F'><i class='fa-brands fa-python'></i> Jupyter</span>"]
    knitr["<span style='color:#1c60b3'><i class='fa-brands fa-r-project'></i> knitr</span>"]
    md["<span style='color:#000000'><i class='fa-brands fa-markdown'></i> md</span>"]
    Pandoc["<span style='color:#000000'><i class='fa-sharp fa-solid fa-arrows-spin'></i> Pandoc</span>"]
    PDF["<span style='color:#FF0000'><i class='fa-regular fa-file-pdf'></i> PDF</span>"]
    Word["<span style='color:#2B579A'><i class='fa-regular fa-file-word'></i> Word</span>"]
    HTML["<span style='color:#f0652b'><i class='fa-regular fa-file-code'></i> HTML</span>"]

    HTML_req["<span style='color:#f0652b'>Nada</span>"]
    WORD_req["<span style='color:#2B579A'>Word o</br>LibreOffice instalado</span>"]
    PDF_req["<span style='color:#FF0000'>quarto install tinytex</span>"]

    qmd ==> Jupyter
    qmd ==> knitr
    knitr ==> md
    Jupyter ==> md
    md ==> Pandoc
    Pandoc ==> HTML
    Pandoc ==> Word
    Pandoc ==> PDF
    HTML == Requiere ==> HTML_req
    Word == Requiere ==> WORD_req
    PDF == Requiere ==> PDF_req

4.2 Escritura en Markdown

Seguiremos esta guía de Quarto

Tip

Símbolos en LaTeX

4.3 Instalación de pre-commit

Vaya a Github y crea un nuevo repositorio llamado Bitácoras Grupo #<su número>, CA-0204 (II-2024) Dele la opción que dice agregar README.md
Vaya a su computadora y en alguna carpeta de trabajo ejecute git clone <url del repositorio>
Recuerden haber instalado pre-commit con pip install pre-commit.

En el archivo genere un nuevo archivo .pre-commit-config.yaml con el siguiente contenido:

# All available hooks: https://pre-commit.com/hooks.html
# R specific hooks: https://github.com/lorenzwalthert/precommit
repos:
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.4.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]
        args: [] # optional: list of Conventional Commits types to allow e.g. [feat, fix, ci, chore, test]

Una vez que logren resolver todos los problemas de instalación con pre-commit y un error que Rstudio no puede ser encontrado, entonces pueden modificar el archivo .pre-commit-config.yaml para que quede de la siguiente manera:

# All available hooks: https://pre-commit.com/hooks.html
# R specific hooks: https://github.com/lorenzwalthert/precommit
repos:
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.4.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]
        args: [] # optional: list of Conventional Commits types to allow e.g. [feat, fix, ci, chore, test]
  - repo: https://github.com/lorenzwalthert/precommit
    rev: v0.4.3
    hooks:
      - id: style-files
        args: [--style_pkg=styler, --style_fun=tidyverse_style]
      - id: roxygenize
      # codemeta must be above use-tidy-description when both are used
      # -   id: codemeta-description-updated
      # roxygen requires loading pkg -> add dependencies from DESCRIPTION
      - id: use-tidy-description
      - id: spell-check
        exclude: >
          (?x)^(
          .*\.[rR]|
          .*\.feather|
          .*\.jpeg|
          .*\.pdf|
          .*\.png|
          .*\.py|
          .*\.RData|
          .*\.rds|
          .*\.Rds|
          .*\.Rproj|
          .*\.sh|
          (.*/|)\.gitignore|
          (.*/|)\.gitlab-ci\.yml|
          (.*/|)\.lintr|
          (.*/|)\.pre-commit-.*|
          (.*/|)\.Rbuildignore|
          (.*/|)\.Renviron|
          (.*/|)\.Rprofile|
          (.*/|)\.travis\.yml|
          (.*/|)appveyor\.yml|
          (.*/|)NAMESPACE|
          (.*/|)renv/settings\.dcf|
          (.*/|)renv\.lock|
          (.*/|)WORDLIST|
          \.github/workflows/.*|
          data/.*|
          )$
      - id: lintr
        args: [--warn_only]
      - id: readme-rmd-rendered
      - id: parsable-R
      - id: no-browser-statement
      - id: no-debug-statement
      - id: deps-in-desc
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: check-added-large-files
        args: ["--maxkb=2000"]
      - id: file-contents-sorter
        files: '^\.Rbuildignore$'
      - id: end-of-file-fixer
        exclude: '\.Rd'
  - repo: https://github.com/pre-commit-ci/pre-commit-ci-config
    rev: v1.6.1
    hooks:
      # Only reuiqred when https://pre-commit.ci is used for config validation
      - id: check-pre-commit-ci-config
  - repo: local
    hooks:
      - id: forbid-to-commit
        name: Don't commit common R artifacts
        entry: Cannot commit .Rhistory, .RData, .Rds or .rds.
        language: fail
        files: '\.(Rhistory|RData|Rds|rds)$'
        # `exclude: <regex>` to allow committing specific files

ci:
  autoupdate_schedule: monthly
  autoupdate_commit_msg: "chore: pre-commit autoupdate"

En la consola ejecute pre-commit install --hook-type commit-msg
Pruebe la nueva funcionalidad generando un commit con el mensaje commit en formato no convencional.

4.4 Archivo _quarto.yml

Todo las configuraciones para los archivos de salida se encuentran en el archivo _quarto.yml. En este lección estamos interesados en la creación de un libro en formato PDF y HTML. Para esto haremos lo siguiente:

En su carpeta de trabajo, genere un nuevo archivo _quarto.yml, y ponga este contenido:

project:
  type: book
  output-dir: "docs"

lang: es

book:
  title: "Bitácoras Grupo #<su número>, CA-204 (II-2024)"
  author: "Estudiante A, Estudiante B, Estudiante C"
  date: today
  site-url: # Vacío por el momento
  chapters:
    - "index.qmd"

bibliography: references.bib

format:
  html:
      # Pueden usar cualquier tema de los que están aca:
      # https://quarto.org/docs/output-formats/html-themes.html a excepción de
      # los oscuros porque no entiende nada.
    theme: cosmo
  pdf:
    documentclass: scrreprt

execute:
  freeze: auto
  cache: true

from: markdown+tex_math_single_backslash+emoji
link-external-newwindow: true

Ahora genere un archivo index.qmd y escriba este contenido

# Introducción {.unnumbered}

<Expliquen en consiste su trabajo y cómo piensan resolverlo>

Use el botón render o el comando en consola quarto preview.

4.5 Conexión del documento Quarto con sitio en Github.

Vaya al repositorio de Github y revisa estos pasos
Asegurate que donde diga Branch (O Rama), aparezca main /docs

4.6 Ahora si a trabajar.

Trabajen en su archivo Quarto. Genere un nuevo archivo que llame bitacora-1.qmd con el contenido respectiivo
```
 # Bitácora 1 

 <Escriba aquí su bitácora>
```
Generen commits de modo que vaya reflejando su trabajo. Debe separar su trabajo en:
- fix: Arregla cosas del código o el texto.
- feat: Agrega cosas nuevas funcionalidades al código o secciones al texto.
- chore: Cambios en el repositorio que no afectan el código o el texto. Estos cambios son los archivos .gitignore, .pre-commit-config.yaml, _quarto.yml, y la carpeta docs.
Para generar todo el sitio delen “Build” o git quarto render en la consola. Recuerden usar commits de tipo chore: para actualizar el sitio web.
Ejecuten git push para que se vean reflejados en el sitio de Github.
Ejecute el comando git tag vBitacora-1 cuando tengan la primera bitácora lista.

4.7 Git-cliff y git summary

SI ya tienen instalado git-cliff y git-extras

Entonces la primera vez que ejecuten git cliff les generará un archivo CHANGELOG.md con la historia de los commits.

git cliff -o CHANGELOG.md

Finalmente para conocer el estado de participación de su grupo ejecute

git summary