write-vignetteCrear viñetas para paquetes R usando R Markdown o Quarto. Cubre la configuración de viñetas, la configuración YAML, las opciones de fragmentos de código, la compilación y las pruebas, y los requisitos de CRAN para viñetas. Usar al añadir un tutorial de introducción, documentar flujos de trabajo complejos que abarcan múltiples funciones, crear guías específi…
Independent GitHub snapshot · Automated classification · Original documentation governs
Crear documentación extensa en forma de viñetas para paquetes R.
usethis::use_vignette("getting-started", title = "Getting Started with packagename")
Esperado: vignettes/getting-started.Rmd creado con cabecera YAML. knitr y rmarkdown añadidos al campo Suggests de DESCRIPTION. El directorio vignettes/ existe.
En caso de fallo: Si usethis::use_vignette() falla, verificar que el directorio de trabajo es la raíz del paquete (contiene DESCRIPTION). Si knitr no está instalado, ejecutar primero install.packages("knitr"). Para la creación manual, crear el directorio vignettes/ y el archivo a mano, asegurándose de que la cabecera YAML incluye las tres entradas %\Vignette*.
---
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:
```r
# 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.
Esperado: El archivo Rmd de la viñeta contiene secciones de Introducción, Instalación, Uso Básico, Funciones Avanzadas y Conclusión. Los ejemplos de código usan las funciones exportadas del paquete y producen salida visible.
En caso de fallo: Si los ejemplos fallan al ejecutarse, verificar que el paquete está instalado con devtools::install(). Asegurarse de que los ejemplos usan el nombre del paquete en las llamadas library() (no devtools::load_all()). Para funciones que requieren recursos externos, usar eval=FALSE para mostrar el código sin ejecutarlo.
Usar opciones de fragmentos para distintos propósitos:
# Fragmento evaluado estándar
{r example-basic}
result <- compute_something(1:10)
result
# Mostrar código pero no ejecutar (con fines ilustrativos)
{r api-example, eval=FALSE}
connect_to_api(key = "your_key_here")
# Ejecutar pero ocultar el código (mostrar solo la salida)
{r hidden-setup, echo=FALSE}
library(packagename)
# Configurar opciones globales
{r setup, include=FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.width = 7,
fig.height = 5
)
Esperado: Un fragmento de configuración con include=FALSE establece las opciones globales (collapse, comment, fig.width, fig.height). Los fragmentos están configurados apropiadamente: eval=FALSE para código ilustrativo, echo=FALSE para la configuración oculta, y fragmentos estándar para los ejemplos interactivos.
En caso de fallo: Si las opciones de fragmento no surten efecto, verificar que la sintaxis usa el formato {r chunk-name, option=value} (separado por comas, sin comillas alrededor de valores lógicos). Comprobar que el fragmento de configuración se ejecuta primero colocándolo al principio del documento.
Para viñetas que necesitan acceso a la red o paquetes opcionales:
{r check-available, include=FALSE}
has_suggested <- requireNamespace("optionalpkg", quietly = TRUE)
{r use-suggested, eval=has_suggested}
optionalpkg::special_function()
Para cálculos de larga duración, precomputar y guardar los resultados:
# Save pre-computed results to vignettes/
saveRDS(expensive_result, "vignettes/precomputed.rds")
# Load in vignette
{r load-precomputed}
result <- readRDS("precomputed.rds")
Esperado: Las dependencias externas se gestionan con elegancia: los paquetes opcionales se cargan condicionalmente con requireNamespace(), el código dependiente de la red usa eval=FALSE o tryCatch(), y los cálculos costosos usan archivos .rds precomputados.
En caso de fallo: Si la viñeta falla en CRAN por paquetes opcionales no disponibles, envolver esas secciones con una variable condicional (p. ej., eval=has_suggested). Para resultados precomputados, asegurarse de que el archivo .rds está incluido en el directorio vignettes/ y se referencia con una ruta relativa.
# Build single vignette
devtools::build_vignettes()
# Build and check (catches vignette issues)
devtools::check()
Esperado: La viñeta compila sin errores. La salida HTML es legible.
En caso de fallo:
RSTUDIO_PANDOC en .Renvirondevtools::install()devtools::check()
Verificaciones relacionadas con viñetas: compila correctamente, no tarda demasiado, sin errores.
Esperado: devtools::check() pasa sin errores ni advertencias relacionados con viñetas. La viñeta compila dentro de los límites de tiempo de CRAN (generalmente menos de 60 segundos).
En caso de fallo: Si la viñeta provoca fallos en la verificación, las correcciones más comunes son: añadir los paquetes Suggests faltantes a DESCRIPTION, reducir el tiempo de compilación con eval=FALSE en fragmentos lentos, y asegurarse de que VignetteIndexEntry coincide con el título. Ejecutar devtools::build_vignettes() por separado para aislar los errores específicos de la viñeta.
devtools::build_vignettes()devtools::check() pasa sin advertencias de viñetavignette(package = "pkg")vignette: Las tres líneas %\Vignette* son obligatoriaseval=FALSE para operaciones costosasRSTUDIO_PANDOC está configuradalibrary(packagename) no devtools::load_all() en las viñetaswrite-roxygen-docs - los documentos a nivel de función complementan los tutoriales de las viñetasbuild-pkgdown-site - las viñetas aparecen como artículos en el sitio pkgdownsubmit-to-cran - CRAN tiene requisitos específicos para las viñetascreate-quarto-report - Quarto como alternativa a las viñetas de R Markdown