pjt222/write-vignette

Vignette schreiben

Ausfuehrliche Dokumentationsvignetten fuer R-Pakete erstellen.

Wann verwenden

• Ein "Getting Started"-Tutorial fuer ein Paket hinzufuegen
• Komplexe Arbeitsablaeufe dokumentieren, die mehrere Funktionen umfassen
• Domaenenspezifische Anleitungen erstellen (z.B. statistische Methodik)
• CRAN-Einreichung erfordert benutzerseitige Dokumentation jenseits von Funktionshilfe

Eingaben

• Erforderlich: R-Paket mit zu dokumentierenden Funktionen
• Erforderlich: Vignetten-Titel und Thema
• Optional: Format (R Markdown oder Quarto, Standard: R Markdown)
• Optional: Ob die Vignette externe Daten oder APIs benoetigt

Vorgehensweise

Schritt 1: Vignetten-Datei erstellen

usethis::use_vignette("getting-started", title = "Getting Started with packagename")

Erwartet: vignettes/getting-started.Rmd mit YAML-Frontmatter erstellt. knitr und rmarkdown zum Suggests-Feld in DESCRIPTION hinzugefuegt. Das Verzeichnis vignettes/ existiert.

Bei Fehler: Wenn usethis::use_vignette() fehlschlaegt, pruefen, ob das Arbeitsverzeichnis das Paketstammverzeichnis ist (enthaelt DESCRIPTION). Wenn knitr nicht installiert ist, zuerst install.packages("knitr") ausfuehren. Bei manueller Erstellung das Verzeichnis vignettes/ und die Datei von Hand anlegen und sicherstellen, dass das YAML-Frontmatter alle drei %\Vignette*-Eintraege enthaelt.

Schritt 2: Vignetten-Inhalt schreiben

---
title: "Getting Started with packagename"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with packagename}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction

Brief overview of what the package does and who it's for.

## Installation

```r
install.packages("packagename")
library(packagename)

Basic Usage

Walk through the primary workflow:

# Load example data
data <- example_data()

# Process
result <- main_function(data, option = "default")

# Inspect
summary(result)

Advanced Features

Cover optional or advanced functionality.

Conclusion

Summarize and point to other vignettes or resources.

**Erwartet:** Die Vignetten-Rmd-Datei enthaelt die Abschnitte Introduction, Installation, Basic Usage, Advanced Features und Conclusion. Code-Beispiele verwenden die exportierten Funktionen des Pakets und liefern sichtbare Ausgaben.

**Bei Fehler:** Wenn Beispiele nicht ausfuehren, pruefen, ob das Paket mit `devtools::install()` installiert ist. Sicherstellen, dass Beispiele den Paketnamen in `library()`-Aufrufen verwenden (nicht `devtools::load_all()`). Fuer Funktionen, die externe Ressourcen benoetigen, `eval=FALSE` verwenden, um Code ohne Ausfuehrung anzuzeigen.

### Schritt 3: Code-Chunks konfigurieren

Chunk-Optionen fuer verschiedene Zwecke verwenden:

```r
# Standard ausgewerteter Chunk
{r example-basic}
result <- compute_something(1:10)
result

# Code anzeigen, aber nicht ausfuehren (fuer illustrative Zwecke)
{r api-example, eval=FALSE}
connect_to_api(key = "your_key_here")

# Ausfuehren, aber Code verbergen (nur Ausgabe anzeigen)
{r hidden-setup, echo=FALSE}
library(packagename)

# Globale Optionen setzen
{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)

Erwartet: Ein Setup-Chunk mit include=FALSE setzt globale Optionen (collapse, comment, fig.width, fig.height). Chunks sind angemessen konfiguriert: eval=FALSE fuer illustrativen Code, echo=FALSE fuer verstecktes Setup und Standard-Chunks fuer interaktive Beispiele.

Bei Fehler: Wenn Chunk-Optionen nicht wirksam werden, pruefen, ob die Syntax das Format {r chunk-name, option=value} verwendet (kommagetrennt, keine Anfuehrungszeichen um logische Werte). Sicherstellen, dass der Setup-Chunk zuerst laeuft, indem er am Anfang des Dokuments platziert wird.

Schritt 4: Externe Abhaengigkeiten behandeln

Fuer Vignetten, die Netzwerkzugriff oder optionale Pakete benoetigen:

{r check-available, include=FALSE}
has_suggested <- requireNamespace("optionalpkg", quietly = TRUE)

{r use-suggested, eval=has_suggested}
optionalpkg::special_function()

Fuer zeitaufwendige Berechnungen Ergebnisse vorausberechnen und speichern:

# Vorberechnete Ergebnisse in vignettes/ speichern
saveRDS(expensive_result, "vignettes/precomputed.rds")

# In der Vignette laden
{r load-precomputed}
result <- readRDS("precomputed.rds")

Erwartet: Externe Abhaengigkeiten werden angemessen behandelt: Optionale Pakete werden bedingt mit requireNamespace() geladen, netzwerkabhaengiger Code verwendet eval=FALSE oder tryCatch(), und aufwendige Berechnungen verwenden vorberechnete .rds-Dateien.

Bei Fehler: Wenn die Vignette bei CRAN wegen nicht verfuegbarer optionaler Pakete fehlschlaegt, diese Abschnitte mit einer Bedingungsvariable umschliessen (z.B. eval=has_suggested). Bei vorberechneten Ergebnissen sicherstellen, dass die .rds-Datei im Verzeichnis vignettes/ enthalten ist und mit relativem Pfad referenziert wird.

Schritt 5: Vignette bauen und testen

# Einzelne Vignette bauen
devtools::build_vignettes()

# Bauen und pruefen (erkennt Vignetten-Probleme)
devtools::check()

Erwartet: Vignette baut ohne Fehler. HTML-Ausgabe ist lesbar.

Bei Fehler:

• Fehlendes pandoc: RSTUDIO_PANDOC in .Renviron setzen
• Paket nicht installiert: Zuerst devtools::install() ausfuehren
• Fehlende Suggests: Im Suggests von DESCRIPTION aufgefuehrte Pakete installieren

Schritt 6: In der Paketpruefung verifizieren

devtools::check()

Vignetten-bezogene Pruefungen: Baut korrekt, dauert nicht zu lange, keine Fehler.

Erwartet: devtools::check() besteht ohne vignetten-bezogene Fehler oder Warnungen. Die Vignette baut innerhalb der CRAN-Zeitlimits (in der Regel unter 60 Sekunden).

Bei Fehler: Wenn die Vignette Pruefungsfehler verursacht, haeufige Korrekturen: fehlende Suggests-Pakete zu DESCRIPTION hinzufuegen, Bauzeit mit eval=FALSE bei langsamen Chunks reduzieren und sicherstellen, dass VignetteIndexEntry mit dem Titel uebereinstimmt. devtools::build_vignettes() separat ausfuehren, um vignetten-spezifische Fehler zu isolieren.

Validierung

• [ ] Vignette baut ohne Fehler via devtools::build_vignettes()
• [ ] Alle Code-Chunks werden korrekt ausgefuehrt
• [ ] VignetteIndexEntry stimmt mit dem Titel ueberein
• [ ] devtools::check() besteht ohne Vignetten-Warnungen
• [ ] Vignette erscheint in den Artikeln der pkgdown-Website (falls zutreffend)
• [ ] Bauzeit ist vertretbar (< 60 Sekunden fuer CRAN)

Haeufige Stolperfallen

• VignetteIndexEntry-Abweichung: Der Indexeintrag im YAML muss dem entsprechen, was Nutzer in vignette(package = "pkg") sehen sollen
• Fehlendes vignette-YAML-Block: Alle drei %\Vignette*-Zeilen sind erforderlich
• Vignette zu langsam fuer CRAN: Ergebnisse vorausberechnen oder eval=FALSE fuer aufwendige Operationen verwenden
• Pandoc nicht gefunden: Sicherstellen, dass die Umgebungsvariable RSTUDIO_PANDOC gesetzt ist
• Selbstreferenzierendes Paket: In Vignetten library(packagename) statt devtools::load_all() verwenden

Verwandte Skills

• write-roxygen-docs - Funktionsdokumentation ergaenzt Vignetten-Tutorials
• build-pkgdown-site - Vignetten erscheinen als Artikel auf der pkgdown-Website
• submit-to-cran - CRAN hat spezifische Vignetten-Anforderungen
• create-quarto-report - Quarto als Alternative zu R Markdown-Vignetten