Renderizar Documentacion de Rompecabezas

Renderizar el sitio de documentacion Quarto de jigsawR.

Cuando Usar

• Construir el sitio de documentacion completo despues de cambios de contenido
• Renderizar una sola pagina durante edicion iterativa
• Preparar documentacion para un release o PR
• Depurar errores de renderizado en archivos Quarto .qmd

Entradas

• Requerido: Modo de renderizado (fresh, cached o single)
• Opcional: Ruta especifica del archivo .qmd (para modo de pagina unica)
• Opcional: Si abrir el resultado en un navegador

Procedimiento

Paso 1: Elegir Modo de Renderizado

Esperado: Modo de renderizado seleccionado segun la situacion actual: fresh para cambios de contenido o cache obsoleto, cached para ediciones menores, single para iterar en una pagina.

En caso de fallo: Si no esta seguro de si el cache esta obsoleto, usar renderizado fresh por defecto. Toma mas tiempo pero garantiza salida correcta.

Paso 2: Ejecutar Renderizado

Renderizado fresh (limpia _freeze y _site, re-ejecuta todo el codigo R):

cd /mnt/d/dev/p/jigsawR && bash inst/scripts/render_quarto.sh

Renderizado cached (usa archivos _freeze existentes):

cd /mnt/d/dev/p/jigsawR && bash inst/scripts/render_quarto.sh --cached

Pagina unica (renderizar un archivo .qmd directamente):

QUARTO_EXE="/mnt/c/Program Files/RStudio/resources/app/bin/quarto/bin/quarto.exe"
"$QUARTO_EXE" render quarto/getting-started.qmd

Esperado: El renderizado se completa sin errores. Salida en quarto/_site/.

En caso de fallo:

• Verificar errores de codigo R en chunks .qmd (buscar marcadores #| label:)
• Verificar que pandoc esta disponible via la variable de entorno RSTUDIO_PANDOC
• Intentar limpiar cache: rm -rf quarto/_freeze quarto/_site
• Verificar que todos los paquetes R usados en archivos .qmd estan instalados

Paso 3: Verificar Salida

ls -la /mnt/d/dev/p/jigsawR/quarto/_site/index.html

Confirmar la estructura del sitio:

• quarto/_site/index.html existe
• Los enlaces de navegacion se resuelven correctamente
• Las imagenes y archivos SVG se renderizan correctamente

Esperado: index.html existe y no esta vacio. Los enlaces de navegacion se resuelven y las imagenes/SVGs se renderizan correctamente en el navegador.

En caso de fallo: Si index.html falta, el renderizado probablemente fallo silenciosamente. Re-ejecutar con salida detallada y verificar errores de codigo R en chunks .qmd. Si solo faltan algunas paginas, verificar que esos archivos .qmd estan listados en _quarto.yml.

Paso 4: Vista Previa (Opcional)

Abrir en el navegador de Windows:

cmd.exe /c start "" "D:\\dev\\p\\jigsawR\\quarto\\_site\\index.html"

Esperado: El sitio de documentacion se abre en el navegador predeterminado de Windows para inspeccion visual.

En caso de fallo: Si el comando cmd.exe /c start falla desde WSL, intentar explorer.exe "D:\\dev\\p\\jigsawR\\quarto\\_site\\index.html" en su lugar. Alternativamente, navegar al archivo manualmente en el navegador.

Validacion

• quarto/_site/index.html existe y no esta vacio
• Sin errores de renderizado en la salida de consola
• Todos los chunks de codigo R se ejecutaron exitosamente (verificar mensajes de error)
• La navegacion entre paginas funciona
• Todos los archivos .qmd tienen #| label: en los chunks de codigo para salida limpia

Errores Comunes

• Cache freeze obsoleto: Si el codigo R cambio, usar renderizado fresh para regenerar archivos _freeze
• Paquetes R faltantes: Los archivos Quarto .qmd pueden usar paquetes que no estan en renv; instalarlos primero
• Pandoc no encontrado: Asegurar que RSTUDIO_PANDOC esta configurado en .Renviron
• Tiempos de renderizado largos: El renderizado fresh toma 5-7 minutos (14 paginas con ejecucion R); usar modo cached durante la iteracion
• Etiquetas de chunks de codigo: Todos los chunks de codigo R deben tener #| label: para renderizado limpio

Habilidades Relacionadas

• generate-puzzle -- generar salida de rompecabezas referenciada en la documentacion
• run-puzzle-tests -- asegurar que los ejemplos de codigo en la documentacion son correctos
• create-quarto-report -- creacion general de documentos Quarto