Render Puzzle Docs

Puzzle-Dokumentation rendern

Die jigsawR Quarto-Dokumentationsseite rendern.

Wann verwenden

• Vollstaendige Dokumentationsseite nach Inhaltsaenderungen erstellen
• Einzelne Seite waehrend iterativer Bearbeitung rendern
• Dokumentation fuer ein Release oder PR vorbereiten
• Renderfehler in Quarto-.qmd-Dateien debuggen

Eingaben

• Erforderlich: Render-Modus (fresh, cached oder single)
• Optional: Spezifischer .qmd-Dateipfad (fuer Einzelseiten-Modus)
• Optional: Ob das Ergebnis im Browser geoeffnet werden soll

Vorgehensweise

Schritt 1: Render-Modus waehlen

Erwartet: Render-Modus basierend auf der aktuellen Situation ausgewaehlt: frisch fuer Inhaltsaenderungen oder veralteten Cache, gecacht fuer kleine Aenderungen, einzeln fuer Iteration an einer Seite.

Bei Fehler: Im Zweifelsfall ob der Cache veraltet ist, standardmaessig frisch rendern. Es dauert laenger, garantiert aber korrekte Ausgabe.

Schritt 2: Rendern ausfuehren

Frisches Rendern (loescht _freeze und _site, fuehrt allen R-Code erneut aus):

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

Gecachtes Rendern (verwendet vorhandene _freeze-Dateien):

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

Einzelne Seite (eine .qmd-Datei direkt rendern):

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

Erwartet: Rendern wird ohne Fehler abgeschlossen. Ausgabe in quarto/_site/.

Bei Fehler:

• Auf R-Code-Fehler in .qmd-Chunks pruefen (nach #| label:-Markern suchen)
• Sicherstellen dass pandoc ueber die Umgebungsvariable RSTUDIO_PANDOC verfuegbar ist
• Cache loeschen versuchen: rm -rf quarto/_freeze quarto/_site
• Pruefen ob alle in .qmd-Dateien verwendeten R-Pakete installiert sind

Schritt 3: Ausgabe ueberpruefen

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

Die Seitenstruktur bestaetigen:

• quarto/_site/index.html existiert
• Navigationslinks loesen korrekt auf
• Bilder und SVG-Dateien werden korrekt dargestellt

Erwartet: index.html existiert und ist nicht leer. Navigationslinks loesen auf, und Bilder/SVGs werden im Browser korrekt dargestellt.

Bei Fehler: Wenn index.html fehlt, ist das Rendern wahrscheinlich stillschweigend fehlgeschlagen. Mit ausfuehrlicher Ausgabe erneut ausfuehren und auf R-Code-Fehler in .qmd-Chunks pruefen. Wenn nur einige Seiten fehlen, ueberpruefen ob diese .qmd-Dateien in _quarto.yml aufgefuehrt sind.

Schritt 4: Vorschau (Optional)

Im Windows-Browser oeffnen:

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

Erwartet: Die Dokumentationsseite oeffnet sich im Windows-Standardbrowser zur visuellen Pruefung.

Bei Fehler: Wenn der cmd.exe /c start-Befehl aus WSL fehlschlaegt, stattdessen explorer.exe "D:\\dev\\p\\jigsawR\\quarto\\_site\\index.html" versuchen. Alternativ die Datei manuell im Browser aufrufen.

Validierung

• quarto/_site/index.html existiert und ist nicht leer
• Keine Renderfehler in der Konsolenausgabe
• Alle R-Code-Chunks wurden erfolgreich ausgefuehrt (auf Fehlermeldungen pruefen)
• Navigation zwischen Seiten funktioniert
• Alle .qmd-Dateien haben #| label: bei Code-Chunks fuer saubere Ausgabe

Haeufige Stolperfallen

• Veralteter Freeze-Cache: Wenn sich R-Code geaendert hat, frisches Rendern zum Neugenerieren der _freeze-Dateien verwenden
• Fehlende R-Pakete: Quarto-.qmd-Dateien koennten Pakete nutzen die nicht in renv enthalten sind; diese zuerst installieren
• Pandoc nicht gefunden: Sicherstellen dass RSTUDIO_PANDOC in .Renviron gesetzt ist
• Lange Renderzeiten: Frisches Rendern dauert 5-7 Minuten (14 Seiten mit R-Ausfuehrung); gecachten Modus waehrend der Iteration verwenden
• Code-Chunk-Label: Alle R-Code-Chunks sollten #| label: fuer sauberes Rendering haben

Verwandte Skills

• generate-puzzle — Puzzle-Ausgabe generieren auf die in der Dokumentation verwiesen wird
• run-puzzle-tests — Sicherstellen dass Codebeispiele in der Doku korrekt sind
• create-quarto-report — Allgemeine Quarto-Dokumenterstellung