Renderización

Introducción

Esta guía proporciona una visión general de cómo optimizar tus procesos de renderizado de documentos utilizando Quarto. Ya sea que estés trabajando con cuadernos Jupyter o con archivos markdown de Quarto, este tutorial mejorará tu productividad enseñándote:

  • Previsualización de documentos: Previsualiza rápidamente tu trabajo en varios formatos directamente desde la terminal.
  • Renderizado completo: Comprender los diferentes comandos de renderizado para generar salidas HTML, PDF o Docx.
  • Parametrización: Personaliza los documentos dinámicamente estableciendo y utilizando parámetros tanto en entornos Python como R.
  • Estrategias de almacenamiento en caché: Implementar el almacenamiento en caché para acelerar el proceso de renderizado y evitar cálculos redundantes.
  • Controles de ejecución: Utiliza las flexibles opciones de ejecución de Quarto para gestionar cómo y cuándo se ejecuta tu código.


Vista previa

Previsualizar un documento:

Terminal
# Previsualizar como html
quarto preview document.qmd

# previsualizar como pdf
quarto preview document.qmd --to pdf

# previsualizar un cuaderno jupyter
quarto preview document.ipynb

Renderización

Renderizar documentos en diferentes formatos utilizando comandos como:

Terminal
# todos los formatos especificados, por defecto html
quarto render document.qmd

# Renderizar como pdf o docx
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

Para cuadernos Jupyter (.ipynb), utilice: quarto render document.ipynb

Nota

Nota: Para archivos .ipynb, usa --execute para ejecutar celdas durante la renderización (si no las has ejecutado ya en el cuaderno).

Terminal
quarto render notebook.ipynb --execute

También puedes especificar este comportamiento dentro del front matter YAML del cuaderno:

---
title: "Mi bloc de notas"
execute: 
  enabled: true
---

Parametrizar

Establece parámetros para crear diferentes variaciones de un documento usando Jupyter o Knitr:

  • En Jupyter, Quarto adopta la sintaxis de Papermill para los parámetros.
  • Etiquetar una celda con parámetros y establecer valores por defecto para parametrizar un documento.
```{python}
#| tags: [parameters]

alpha = 0.1
ratio = 0.1
```

Los parámetros están disponibles en el entorno de nivel superior:

```{python}
alpha
```

Utilice la opción params YAML para definir parámetros:

---
params:
  alpha: 0.1
  ratio: 0.1
---

Los parámetros están disponibles en la lista params:

```{r}
params$alpha
```

Renderizar con diferentes parámetros utilizando -P for both .ipynb and .qmd:

quarto render document.ipynb -P alpha:0.2 -P ratio:0.3

O utilizar un archivo YAML para los parámetros y --execute-params:

quarto render document.qmd --execute-params params.yml

Almacenamiento en caché

Caché de ejecución de código para acelerar el renderizado y evitar la reejecución de código sin cambios.

Configuración

La configuración depende del motor de ejecución que esté utilizando (Jupyter o Knitr).

Instalar Jupyter Cache:

  • Mac/Linux python3 -m pip install jupyter-cache
  • Windows py -m pip install jupyter-cache

Habilitar caché globalmente en YAML:

---
title: "Mi documento"
format: html
execute: 
  cache: true
---

O a nivel de proyecto:

project:
  type: website
  
format:
  html:
    theme: united
    
execute:
  cache: true
Nota

Si lo desea, puede utilizar la línea de comandos jcache para gestionar la caché de las libretas. Ver documentación Jupyter Cache.

Habilitar caché globalmente en YAML:

---
title: "Mi documento"
format: html
execute: 
  cache: true
---

O individualmente por celda:

```{r}
#| cache: true

summary(cars)
```

Leer más:

Renderización

Puedes usar las opciones de línea de comandos quarto render para controlar el comportamiento de la caché sin cambiar el código del documento.

Controlar la caché de quarto render con opciones de línea de comandos:

  • --cache: Forzar caché para todos los chunks (incluso si no está habilitado en las opciones).
  • --no-cache: Desactivar la caché para todos los chunks (incluso si está activada en las opciones).
  • --cache-refresh: Refrescar caché para todos los chunks (incluso si no ha sido invalidado).

Alternativas

Desactivar la ejecución

Para trabajar con prosa/markdown, deshabilite la ejecución de código con:

execute: 
  enabled: false

En los cuadernos Jupyter .ipynb, el código no se ejecuta con quarto render por defecto.

Congelar la ejecución

La opción freeze evita que los documentos se vuelvan a renderizar durante una renderización completa del proyecto o permite que se vuelvan a renderizar sólo cuando cambia su fuente.

# No volver a renderizar durante la renderización del proyecto
execute:
  freeze: true  
# Renderizar sólo cuando la fuente cambia
execute:
  freeze: auto

Freeze afecta a la ejecución durante el renderizado completo del proyecto. Para documentos individuales o renderizaciones de subdirectorios, la ejecución del código se realiza siempre.

Terminal
# Renderizar un único documento (siempre ejecuta el código)
quarto render document.qmd

# Renderizar subdirectorio de proyecto (siempre ejecuta código)
quarto render articles

Referencias