17  Viñetas

Una viñeta es una guía detallada de su paquete. La documentación de funciones es excelente si conoce el nombre de la función que necesita, pero de lo contrario es inútil. Por el contrario, una viñeta se puede enmarcar en torno a un problema objetivo que su paquete está diseñado para resolver. El formato de viñeta es perfecto para mostrar un flujo de trabajo que resuelve ese problema en particular, de principio a fin. Las viñetas le brindan diferentes oportunidades que los temas de ayuda: tiene mucho más control sobre la integración del código y la prosa y es una mejor configuración para mostrar cómo funcionan múltiples funciones juntas.

Muchos paquetes existentes tienen viñetas y puede ver todas las viñetas asociadas con sus paquetes instalados con browseVignettes(). Para limitar eso a un paquete en particular, puede especificar el nombre del paquete así: browseVignettes("tidyr"). Puede leer una viñeta específica con la función vignette(), por ejemplo, vignette("rectangle", package = "tidyr"). Para ver viñetas de un paquete que no ha instalado, consulte la lista “Viñetas” en su página CRAN, por ejemplo. https://cran.r-project.org/web/packages/tidyr/index.html.

Sin embargo, preferimos descubrir y leer viñetas del sitio web de un paquete, que es el tema de Capítulo 191. Compare lo anterior con lo que se siente al acceder a las viñetas de tidyr desde su sitio web: https://tidyr.tidyverse.org/articles/index.html. Tenga en cuenta que pkgdown utiliza el término “artículo”, que parece el vocabulario adecuado para los usuarios del paquete. La distinción técnica entre una viñeta (que se envía con un paquete) y un artículo (que solo está disponible en el sitio web; consulte Sección 17.4.1) es algo en lo que el desarrollador del paquete debe pensar. Un sitio web pkgdown presenta toda la documentación de un paquete de una manera coherente e interconectada que lo hace más navegable y útil. Aparentemente, este capítulo trata sobre viñetas, pero la forma en que hacemos las cosas está fuertemente influenciada por cómo esas viñetas encajan en un sitio web pkgdown.

En este libro, usaremos R Markdown para escribir nuestras viñetas2, tal como lo hicimos para la documentación de funciones en Sección 16.1.3. Si aún no está familiarizado con R Markdown, necesitará aprender los conceptos básicos en otro lugar; un buen lugar para empezar es https://rmarkdown.rstudio.com/.

En general, adoptamos un flujo de trabajo de viñeta algo circunscrito, es decir, hay muchas cosas que la base R permite, en las que simplemente no participamos. Por ejemplo, tratamos inst/doc/3 de la misma manera que man/ y NAMESPACE, es decir, como algo semiopaco que se gestiona mediante herramientas automatizadas y que no modificamos. manualmente. El sistema de viñetas de Base R permite varias maniobras complicadas que simplemente intentamos evitar. En las viñetas, más que en cualquier otro lugar, la respuesta a “¿Pero cómo hago X?” suele ser “No hagas X”.

17.1 Flujo de trabajo para escribir una viñeta

Para crear su primera viñeta, ejecute:

usethis::use_vignette("my-vignette")

Esto hace lo siguiente:

  1. Crea un directorio viñetas/.

  2. Agrega las dependencias necesarias a DESCRIPCIÓN, es decir, agrega knitr al campo VignetteBuilder y agrega knitr y rmarkdown a Suggests.

  3. Redacta una viñeta, vignettes/my-vignette.Rmd.

  4. Agrega algunos patrones a .gitignore para garantizar que los archivos creados como efecto secundario de la vista previa de sus viñetas se mantengan fuera del control de fuente (diremos más sobre esto más adelante).

Este borrador del documento tiene los elementos clave de una viñeta de R Markdown y le permite agregar su contenido. También llama a use_vignette() para crear su segunda viñeta y todas las siguientes; simplemente omitirá cualquier configuración que ya se haya realizado.

Una vez que tenga el borrador de la viñeta, el flujo de trabajo es sencillo:

  1. Comience a agregar prosa y fragmentos de código a la viñeta. Utilice devtools::load_all() según sea necesario y utilice su flujo de trabajo interactivo habitual para desarrollar los fragmentos de código.

  2. Renderice periódicamente la viñeta completa.

    Esto requiere cierta intención, porque a diferencia de las pruebas, de forma predeterminada, una viñeta se representa usando la versión actualmente instalada de su paquete, no con el paquete fuente actual, gracias a la llamada inicial a library(supaquete).

    Una opción es instalar correctamente su paquete fuente actual con devtools::install() o, en RStudio, Ctrl/Cmd + Shift + B. Luego use su flujo de trabajo habitual para renderizar un archivo .Rmd. Por ejemplo, presione Ctrl/Cmd + Shift + K o haga clic en .

    O puede instalar correctamente su paquete y solicitar que se creen viñetas, con install(build_vignettes = TRUE), luego usar browseVignettes().

    Otra opción es usar devtools::build_rmd("vignettes/my-vignette.Rmd") para representar la viñeta. Esto construye su viñeta contra una versión de desarrollo (instalada temporalmente) de su paquete.

    Es muy fácil pasar por alto este problema y quedar desconcertado cuando la vista previa de su viñeta no parece reflejar los desarrollos recientes en el paquete. ¡Comprueba que estás compilando con la versión actual!

  3. Enjuague y repita hasta que la viñeta luzca como desea.

Si revisa periódicamente todo su paquete (Sección 4.5), lo cual recomendamos encarecidamente, esto ayudará a mantener sus viñetas en buen estado de funcionamiento. En particular, esto le alertará si una viñeta utiliza un paquete que no es una dependencia formal. Volveremos a estos problemas de flujo de trabajo a nivel de paquete a continuación en Sección 17.5.

17.2 Metadatos

Las primeras líneas de la viñeta contienen metadatos importantes. La plantilla predeterminada contiene la siguiente información:

---
title: "Título de viñeta"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

Estos metadatos están escritos en YAML, un formato diseñado para ser legible tanto por humanos como por computadoras. El frontmatter YAML es una característica común de los archivos R Markdown. La sintaxis es muy parecida a la del archivo DESCRIPTION, donde cada línea consta de un nombre de campo, dos puntos y luego el valor del campo. La única característica especial de YAML que estamos usando aquí es >. Indica que las siguientes líneas de texto son texto sin formato y no deben utilizar ninguna característica especial de YAML.

La plantilla de viñeta predeterminada utiliza estos campos:

  • title: este es el título que aparece en la viñeta. Si lo cambia, asegúrese de realizar el mismo cambio en VignetteIndexEntry{}. Deberían ser iguales, pero lamentablemente eso no es automático.

  • salida: esto especifica el formato de salida. Hay muchas opciones que son útiles para informes regulares (incluidos html, pdf, presentaciones de diapositivas, etc.), pero rmarkdown::html_vignette ha sido diseñado específicamente para este propósito exacto. Consulte ?rmarkdown::html_vignette para obtener más detalles.

  • vignette: este es un bloque de metadatos especiales que necesita R. Aquí puede ver el legado de las viñetas de LaTeX: los metadatos parecen comentarios de LaTeX. La única entrada que quizás necesite modificar es \VignetteIndexEntry{}. Así es como aparece la viñeta en el índice de viñetas y debe coincidir con el “título”. Deja las otras dos líneas en paz. Le dicen a R que use knitr para procesar el archivo y que el archivo esté codificado en UTF-8 (la única codificación que debería usar para una viñeta).

Generalmente no usamos estos campos, pero los verá en otros paquetes:

  • autor: no usamos esto a menos que la viñeta esté escrita por alguien que aún no esté acreditado como autor del paquete.

  • date: creemos que esto suele hacer más daño que bien, ya que no está claro qué pretende transmitir la date. ¿Es la última vez que se actualizó la fuente de la viñeta? En ese caso, tendrás que administrarlo manualmente y es fácil olvidarte de actualizarlo. Si administra date programáticamente con Sys.date(), la fecha refleja cuándo se creó la viñeta, es decir, cuándo se creó el paquete, que no tiene nada que ver con cuándo se modificó por última vez la viñeta o el paquete. Hemos decidido que es mejor omitir la date.

El borrador de la viñeta también incluye dos fragmentos de R. El primero configura nuestra forma preferida de mostrar la salida del código y tiene este aspecto:

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

El segundo fragmento simplemente adjunta el paquete al que pertenece la viñeta.

```{r setup}
library(yourpackage)
```

Es posible que tenga la tentación de reemplazar (temporalmente) esta llamada library() con load_all(), pero le recomendamos que no lo haga. En su lugar, utilice las técnicas proporcionadas en Sección 17.1 para ejercitar su código de viñeta con el paquete fuente actual.

17.3 Consejos para escribir viñetas

Si estás pensando sin escribir, sólo piensas que estás pensando. — Leslie Lamport

Al escribir una viñeta, le estás enseñando a alguien cómo usar tu paquete. Debe ponerse en el lugar del lector y adoptar una “mente de principiante”. Esto puede resultar difícil porque es difícil olvidar todo el conocimiento que ya ha interiorizado. Por este motivo, consideramos que la enseñanza presencial es una forma realmente útil de obtener retroalimentación. Inmediatamente te enfrentas a lo que has olvidado y que sólo tú sabes.

Un efecto secundario útil de este enfoque es que le ayuda a mejorar su código. Te obliga a volver a ver el proceso de incorporación inicial y a apreciar las partes que son difíciles. Nuestra experiencia es que explicar cómo funciona el código a menudo revela algunos problemas que deben solucionarse.

De hecho, una parte clave del proceso de lanzamiento del paquete tidyverse es escribir una publicación en el blog: ahora lo hacemos antes de enviarlo a CRAN, debido a la cantidad de veces que se revela algún problema sutil que requiere solución. También es justo decir que tidyverse y sus paquetes de soporte se beneficiarían de más guías prácticas, por lo que es un área en la que intentamos mejorar constantemente.

Escribir una viñeta también supone un buen descanso de la codificación. La escritura parece utilizar una parte del cerebro diferente a la de la programación, así que si estás cansado de la programación, intenta escribir un poco.

Aquí hay algunos recursos que hemos encontrado útiles:

  • Literalmente cualquier cosa escrita por Kathy Sierra. No escribe activamente en este momento, pero su contenido es en su mayor parte atemporal y está lleno de consejos sobre programación, enseñanza y cómo crear herramientas valiosas. Vea su blog original, Creando usuarios apasionados, o el sitio posterior, Serious Pony.

  • “Estilo: Lecciones de claridad y gracia” de Joseph M. Williams y Joseph Bizup. Este libro le ayuda a comprender la estructura de la escritura para que pueda reconocer y corregir mejor la mala escritura.

17.3.1 Diagramas

Envío a CRAN

Tendrás que vigilar el tamaño del archivo. Si incluye muchos gráficos, es fácil crear un archivo muy grande. Esté atento a una “NOTA” que se queja de un directorio demasiado grande. Es posible que debas tomar medidas explícitas, como reducir la resolución, reducir el número de figuras o cambiar de una viñeta a un artículo (Sección 17.4.1).

17.3.2 Enlaces

No existe una forma oficial de vincular temas de ayuda desde viñetas o viceversa o de una viñeta a otra.

Este es un ejemplo concreto de por qué creemos que los sitios pkgdown son una excelente manera de presentar documentación de paquetes, porque pkgdown hace que sea fácil (literalmente sin esfuerzo, en muchos casos) obtener estas referencias cruzadas con hipervínculos. Esto está documentado en vignette("linking", package = "pkgdown"). Si estás leyendo este libro en línea, la llamada en línea a vignette() en la oración anterior debe tener un hipervínculo a la viñeta correspondiente en pkgdown4, usando la misma cadena de herramientas que creará enlaces automáticos en tu pkgdown. sitios web! Discutimos esta sintaxis anteriormente en Sección 16.1.3, en el contexto de la documentación de funciones.

Se generan enlaces automáticos para funciones en el paquete host, funciones calificadas para espacios de nombres en otro paquete, viñetas y más. Estos son los dos ejemplos más importantes de texto vinculado automáticamente:

  • `some_function()`: Autoenlazado a la documentación de some_function(), dentro del sitio pkgdown de su paquete host. Tenga en cuenta el uso de comillas invertidas y paréntesis finales.

  • `vignette("fascinating-topic")`: Vinculado automáticamente al artículo “fascinating-topic” dentro del sitio pkgdown de su paquete host. Tenga en cuenta el uso de comillas invertidas.

17.3.3 Rutas de archivos

A veces es necesario hacer referencia a otro archivo de una viñeta. La mejor manera de hacerlo depende de la aplicación:

  • Una figura creada por código evaluado en la viñeta: De forma predeterminada, en el flujo de trabajo .Rmd que recomendamos, esto se soluciona solo. Estas cifras se incrustan automáticamente en .html mediante URI de datos. No necesitas hacer nada. Ejemplo: vignette("extending-ggplot2", package = "ggplot2") genera algunas cifras en fragmentos de código evaluados.

  • Un archivo externo que podría ser útil para los usuarios o en cualquier otra parte del paquete (no solo en viñetas): coloque dicho archivo en inst/ (Sección 8.2), tal vez en inst/extdata/ (Sección 7.3), y consúltelo con system.file() o fs::path_package() (Sección 7.3.1). Ejemplo de vignette("sf2", package = "sf"):

    
````{r}
library(sf)
fname <- system.file("shape/nc.shp", package="sf")
fname
nc <- st_read(fname)
```

  • Un archivo externo cuya utilidad se limita a sus viñetas: colóquelo junto a los archivos fuente de las viñetas en vignettes/ y consúltelo con una ruta de archivo relativa a vignettes/.

    Ejemplo: la fuente de vignette("tidy-data", package = "tidyr") se encuentra en vignettes/tidy-data.Rmd e incluye un fragmento que lee un archivo ubicado en vignettes/weather.csvasí:

    ```{r}
weather <- as_tibble(read.csv("weather.csv", stringsAsFactors = FALSE))
weather
```

  • Un archivo de gráficos externo: colóquelo en vignettes/, consúltelo con una ruta de archivo relativa a vignettes/ y use knitr::include_graphics() dentro de un fragmento de código. Ejemplo de vignette("sheet-geometry", package = "readxl"):

    
```{r out.width = '70%', echo = FALSE}
knitr::include_graphics("img/geometry.png")
```

17.3.4 ¿Cuántas viñetas?

Para paquetes más simples, una viñeta suele ser suficiente. Si su paquete se llama “algúnpaquete”, llame a esta viñeta algúnpaquete.Rmd. Esto aprovecha una convención pkgdown, donde la viñeta que lleva el nombre del paquete obtiene un enlace automático “Get started” en la barra de navegación superior.

Los paquetes más complicados probablemente necesiten más de una viñeta. Puede resultar útil pensar en las viñetas como capítulos de un libro: deben ser independientes, pero aun así estar unidos formando un todo cohesivo.

17.3.5 Publicación científica

Las viñetas también pueden resultar útiles si desea explicar los detalles de su paquete. Por ejemplo, si ha implementado un algoritmo estadístico complejo, es posible que desee describir todos los detalles en una viñeta para que los usuarios de su paquete puedan entender lo que sucede bajo el capó y estar seguros de que ha implementado el algoritmo correctamente. En este caso, también podría considerar enviar su viñeta al Journal of Statistical Software o The R Journal. Ambas revistas son únicamente electrónicas y están revisadas por pares. Los comentarios de los revisores pueden ser muy útiles para mejorar su paquete y viñeta.

Si solo desea proporcionar algo muy liviano para que la gente pueda citar fácilmente su paquete, considere el Journal of Open Source Software. Esta revista tiene un proceso de envío y revisión particularmente rápido, y es donde publicamos “Welcome to the Tidyverse”, un artículo que escribimos para que la gente pudiera tener un solo artículo para citar y todos los autores de tidyverse obtuvieran algún crédito académico.

17.4 Consideraciones especiales para el código de viñeta

Un tema recurrente es que el código R dentro de un paquete debe escribirse de manera diferente al código en sus scripts e informes de análisis. Esto es cierto para sus funciones (Sección 6.4), pruebas (Sección 14.2) y ejemplos (Sección 16.5), y también es cierto para las viñetas. En términos de lo que puedes y no puedes hacer, las viñetas son bastante similares a los ejemplos, aunque algunas de las mecánicas difieren.

Cualquier paquete utilizado en una viñeta debe ser una dependencia formal, es decir, debe aparecer en Imports o Suggests en DESCRIPTION. De manera similar a nuestra postura en las pruebas (Sección 11.5.2), nuestra política es escribir viñetas bajo el supuesto de que los paquetes sugeridos se instalarán en cualquier contexto donde se esté creando la viñeta (Sección 11.5.3). Generalmente utilizamos paquetes sugeridos incondicionalmente en viñetas. Pero, al igual que con las pruebas, si un paquete es particularmente difícil de instalar, podríamos hacer una excepción y tomar medidas adicionales para proteger su uso.

Hay muchas otras razones por las que podría no ser posible evaluar todo el código en una viñeta en ciertos contextos, como en las máquinas de CRAN o en CI/CD. Estos incluyen todos los sospechosos habituales: falta de credenciales de autenticación, código de ejecución prolongada o código vulnerable a fallas intermitentes.

El método principal para controlar la evaluación en un documento .Rmd es la opción de fragmento de código eval, que puede ser TRUE (el valor predeterminado) o FALSE. Es importante destacar que el valor de eval puede ser el resultado de evaluar una expresión. A continuación se muestran algunos ejemplos relevantes:

  • eval = requireNamespace("algunadependencia")
  • eval = !identical(Sys.getenv("ALGO_QUE_NECESITA"), "")
  • eval = file.exists("credenciales-que-necesita")

La opción eval se puede configurar para un fragmento individual, pero en una viñeta es probable que desees evaluar la mayoría o todos los fragmentos o prácticamente ninguno de ellos. En el último caso, querrás usar knitr::opts_chunk$set(eval = FALSE) en un fragmento inicial oculto para hacer que eval = FALSE sea el valor predeterminado para el resto de la viñeta. Aún puedes anular con eval = TRUE en fragmentos individuales.

En viñetas, usamos la opción eval de manera similar a @examplesIf en los ejemplos (Sección 16.5.4). Si el código solo se puede ejecutar bajo condiciones específicas, debe encontrar una manera de verificar esas condiciones previas mediante programación en tiempo de ejecución y usar el resultado para configurar la opción eval.

Estos son los primeros fragmentos de una viñeta de googlesheets4, que engloba la API de Google Sheets. El código de viñeta solo se puede ejecutar si somos capaces de descifrar un token que nos permita autenticarnos con la API. Ese hecho se registra en can_decrypt, que luego se establece como el valor predeterminado de toda la viñeta para eval.

```{r setup, include = FALSE}
can_decrypt <- gargle:::secret_can_decrypt("googlesheets4")
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  error = TRUE,
  eval = can_decrypt
)
```

```{r eval = !can_decrypt, echo = FALSE, comment = NA}
message("No token available. Code chunks will not be evaluated.")
```

```{r index-auth, include = FALSE}
googlesheets4:::gs4_auth_docs()
```

```{r}
library(googlesheets4)
```

Observe que el segundo fragmento usa eval = !can_decrypt, que imprime un mensaje explicativo para cualquiera que cree la viñeta sin las credenciales necesarias.

El ejemplo anterior muestra algunas opciones de fragmentos más útiles. Utilice include = FALSE para fragmentos que deben evaluarse pero no verse en la viñeta representada. La opción echo controla si se imprime el código, además de la salida. Finalmente, error = TRUE es lo que le permite ejecutar código intencionalmente que podría generar un error. El error aparecerá en la viñeta, tal como lo haría para su usuario, pero no impedirá la ejecución del resto del código de su viñeta, ni provocará que falle la R CMD check. Esto es algo que funciona mucho mejor en una viñeta que en un ejemplo.

Muchas otras opciones se describen en https://yihui.name/knitr/options.

17.4.1 Artículo en lugar de viñeta

Existe una última técnica, si no desea que ningún código se ejecute en CRAN. En lugar de una viñeta, puede crear un artículo, que es un término utilizado por pkgdown para un documento .Rmd similar a una viñeta que no se envía con el paquete, pero que aparece sólo en el sitio web. Un artículo será menos accesible que una viñeta para ciertos usuarios, como aquellos con acceso limitado a Internet, porque no está presente en la instalación local. Pero ese podría ser un compromiso aceptable, por ejemplo, para un paquete que incluye una API web.

Puede redactar un nuevo artículo con usethis::use_article(), lo que garantiza que el artículo será .Rbuildignored. Una buena razón para utilizar un artículo en lugar de una viñeta es mostrar que su paquete funciona en conjunto con otros paquetes de los que no desea depender formalmente. Otro caso de uso atractivo es cuando un artículo realmente exige muchos gráficos. Esto es problemático para una viñeta, porque el gran tamaño del paquete causa problemas con R CMD check (y, por lo tanto, CRAN) y también es una carga para todos los que lo instalan, especialmente aquellos con Internet limitado.

17.5 Cómo se construyen y verifican las viñetas

Cerramos este capítulo volviendo a algunos problemas de flujo de trabajo que no cubrimos en Sección 17.1: ¿Cómo se convierten los archivos .Rmd en viñetas consumidas por los usuarios de un paquete instalado? ¿Qué hace R CMD check con las viñetas? ¿Cuáles son las implicaciones para mantener sus viñetas?

Puede resultar útil apreciar la gran diferencia entre el flujo de trabajo para la documentación de funciones y las viñetas. La fuente de la documentación de la función se almacena en los comentarios de roxygen en archivos .R debajo de R/. Usamos devtools::document() para generar archivos .Rd debajo de man/. Estos archivos man/*.Rd son parte del paquete fuente. La maquinaria oficial de R se preocupa sólo por los archivos .Rd.

Las viñetas son muy diferentes porque la fuente .Rmd se considera parte del paquete fuente y la maquinaria oficial (R CMD build y check) interactúa con la fuente de la viñeta y las viñetas construidas de muchas maneras. El resultado es que el flujo de trabajo de viñetas se siente más restringido, ya que las herramientas oficiales básicamente tratan las viñetas como pruebas, en lugar de documentación.

17.5.1 R CMD build y viñetas

Primero, es importante darse cuenta de que los archivos fuente vignettes/*.Rmd existen solo cuando un paquete está en formato fuente (Sección 3.2) o en formato empaquetado (Sección 3.3). Las viñetas se representan cuando un paquete fuente se convierte en un paquete mediante R CMD build o un contenedor conveniente como devtools::build(). Los productos renderizados (.html) se colocan en inst/doc/, junto con su fuente (.Rmd) y el código R extraído (.R; discutido en Sección 17.5.2) . Finalmente, cuando se crea un paquete binario (Sección 3.4), el directorio inst/doc/ se promueve a un directorio doc/ de nivel superior, como sucede con todo lo que está debajo de inst/.

TLa conclusión clave de lo anterior es que resulta incómodo mantener viñetas renderizadas en un paquete fuente y esto tiene implicaciones para el flujo de trabajo de desarrollo de viñetas. Es tentador luchar contra esto (y muchos lo han intentado), pero basándose en años de experiencia y discusión, la filosofía de devtools es aceptar esta realidad.

Suponiendo que no intenta mantener viñetas creadas de manera persistente en su paquete fuente, aquí están nuestras recomendaciones para varios escenarios:

  • Trabajo activo e iterativo en sus viñetas: use su flujo de trabajo interactivo habitual .Rmd (como el botón ) o devtools::build_rmd("vignettes /my-vignette.Rmd") para representar una viñeta en .html en el directorio vignettes/. Considere el .html como una vista previa desechable. (Si inicia viñetas con use_vignette(), este .html ya será ignorado).

  • Poner a disposición del mundo el estado actual de las viñetas en una versión de desarrollo:

    • Ofrecer un sitio web pkgdown, preferiblemente con “construcción e implementación” automatizada, como el uso de GitHub Actions para implementar en GitHub Pages. Aquí están las viñetas de tidyr en la versión de desarrollo (tenga en cuenta “dev” en la URL): https://tidyr.tidyverse.org/dev/articles/index.html.

    • Tenga en cuenta que cualquiera que instale directamente desde GitHub deberá solicitar viñetas explícitamente, por ejemplo, con devtools::install_github(dependencies = TRUE, build_vignettes = TRUE).

  • Hacer que el estado actual de las viñetas en una versión de desarrollo esté disponible localmente:

    • Instale su paquete localmente y solicite que se creen e instalen viñetas, por ejemplo, con devtools::install(dependencies = TRUE, build_vignettes = TRUE).

  • Prepare viñetas creadas para un envío CRAN: no intente hacerlo a mano o con anticipación. Permita que la (re)compilación de viñetas se realice como parte de devtools::submit_cran() o devtools::release(), los cuales compilan el paquete.

Si realmente desea crear viñetas de manera oficial de forma ad hoc, devtools::build_vignettes() lo hará. Pero hemos visto que esto genera frustración en los desarrolladores, porque deja el paquete en una forma peculiar que es una mezcla de un paquete fuente y un paquete desempaquetado. Esta situación atípica puede generar aún más confusión. Por ejemplo, no está claro cómo se debe acceder a estas viñetas que no están realmente instaladas. La mayoría de los desarrolladores deberían evitar el uso de build_vignettes() y, en su lugar, elegir uno de los enfoques descritos anteriormente.

Viñetas prediseñadas (or other documentation)

Recomendamos encarecidamente tratar inst/doc/ como un directorio estrictamente editable por máquina para viñetas. Le recomendamos que no aproveche el hecho de que puede colocar documentación prediseñada arbitraria en inst/doc/. Esta opinión impregna el ecosistema devtools que, de forma predeterminada, limpia inst/doc/ durante diversas tareas de desarrollo, para combatir el problema de la documentación obsoleta.

Sin embargo, reconocemos que existen excepciones a cada regla. En algunos dominios, puede resultar poco práctico reconstruir viñetas con tanta frecuencia como implica nuestro flujo de trabajo recomendado. Aquí hay algunos consejos:

  • Puedes evitar la limpieza de inst/doc/ con pkgbuild::build(clean_doc =). Puede poner Config/build/clean-inst-doc: FALSE en DESCRIPTION para evitar que pkgbuild y rcmdcheck limpien inst/doc/.

  • La nota técnica de rOpenSci Cómo precalcular viñetas de paquetes o artículos pkgdown describe una técnica inteligente y liviana para mantener una viñeta actualizada manualmente en viñetas/.

  • El paquete R.rsp ofrece soporte explícito para viñetas estáticas.

17.5.2 R CMD check y viñetas

Concluimos con una discusión sobre cómo las viñetas son tratadas por R CMD check. Este verificador oficial espera un paquete creado por R CMD build, como se describe anteriormente. En el flujo de trabajo de devtools, generalmente confiamos en devtools::check(), que realiza automáticamente este paso de compilación por nosotros, antes de verificar el paquete. R CMD check tiene varias opciones de línea de comando y también consulta muchas variables de entorno. Estamos adoptando un enfoque maximalista aquí, es decir, describimos todas las comprobaciones que podrían ocurrir.

R CMD check realiza un análisis estático del código de viñeta y examina la existencia, el tamaño y los tiempos de modificación de varios archivos relacionados con viñetas. Si sus viñetas usan paquetes que no aparecen en DESCRIPTION, eso se recoge aquí. Si los archivos que deberían existir no existen o viceversa, eso se recoge aquí. Esto no debería suceder si utiliza el flujo de trabajo de viñeta estándar descrito en este capítulo y generalmente es el resultado de algún experimento que haya realizado, intencionalmente o no.

Luego, el código de viñeta se extrae en un archivo .R, utilizando la función tangle del motor de viñeta correspondiente (knitr, en nuestro caso), y se ejecuta. El código que se origina a partir de fragmentos marcados como eval = FALSE se comentará en este archivo y, por lo tanto, no se ejecutará. Luego, las viñetas se reconstruyen desde la fuente, utilizando la función weave del motor de viñetas (knitr, para nosotros). Esto ejecuta todo el código de viñeta una vez más, excepto los fragmentos marcados como eval = FALSE.

Envío a CRAN

Las comprobaciones entrantes y en curso de CRAN utilizan R CMD check que, como se describe anteriormente, ejercita el código de viñeta hasta dos veces. Por lo tanto, es importante suprimir condicionalmente la ejecución de código condenado a fallar en CRAN.

Sin embargo, es importante tener en cuenta que el paquete y los archivos binarios distribuidos por CRAN en realidad utilizan las viñetas integradas incluidas en su envío. Sí, CRAN intentará reconstruir sus viñetas periódicamente, pero esto es con fines de control de calidad. CRAN distribuye las viñetas que usted creó.

  1. Esto obviamente depende de la calidad de la conexión a Internet, por lo que nos esforzamos en recomendar comportamientos que sean compatibles con las herramientas de base R en torno a las viñetas instaladas.↩︎

  2. Sweave es el sistema original utilizado para crear viñetas (los archivos Sweave generalmente tienen la extensión .Rnw). De manera similar a nuestro consejo sobre cómo crear documentación de funciones (Capítulo 16), creemos que tiene más sentido usar una sintaxis basada en rebajas para viñetas que un formato único asociado a LaTeX. Esta elección también afecta la forma de las viñetas renderizadas: las viñetas Sweave se renderizan en PDF, mientras que las viñetas R Markdown se renderizan en HTML. Recomendamos convertir viñetas de Sweave a R Markdown.↩︎

  3. La carpeta inst/doc/ es donde van las viñetas una vez creadas, cuando R CMD build crea el paquete.↩︎

  4. Y, para cualquier otra persona, ejecutar este código en la consola R abrirá la viñeta, si el paquete host está instalado.↩︎