Incluir tutoriales: creación de viñetas (Creación de paquetes en R 7ª parte)

La semana pasada hemos visto cómo crear la documentación de nuestros paquetes de R mediante el uso de roxygen2. Documentación que es imprescindible a la hora de trabajar con cualquier librería. Pero, en la mayoría de los casos lo que realmente buscan los usuarios a la hora de empezar a usar un paquete nuevo es un tutorial con ejemplos en los que se enseñan algunos usos prácticos del software. En los paquetes de R estos tutoriales se denominan "viñetas" (vignettes), siendo la creación de viñetas el tema que trataremos esta semana.

Inclusión de viñetas

Posiblemente la inclusión de una viñeta en un paquete R la una de las tareas más sencilla a la hora de crear un paquete, solamente se tiene que incluir el documento. Aunque una de las tareas más complicadas posiblemente sea la escritura del documento. Las viñetas se pueden escribir en LaTeX (para lo que se puede usar Sweave o knitr), pero es mucho más fácil usar R Markdown.

R Markdown

Markdown es un lenguaje de marcado ligero que mediante el uso de asteriscos u otros símbolos permiten dar una estructura en archivos de texto plano. Lo que hace que sea altamente portable. Por ejemplo, es el lenguaje de marcado que se usa en los documentos de Jupyter Notebook para incluir celdas con comentarios. R Markdown es una extensión de Markdown en el que se puede incluir fragmentos de código R. Los documentos de R Markdown se pueden transformar, mediante knitr, en documento de Markdown, reemplazando el código R con sus resultados. Para, posteriormente, convertir estos en archivos HTML u otros formatos para su lectura. Aunque los documentos Markdown también se pueden leer directamente sin problemas.

Creación de viñetas con R Markdown

Para incluir una viñeta en formato R Markdown dentro de nuestro paquete R solamente se tiene crear una carpeta vignettes en nuestro proyecto e incluir en ella los archivos R Markdown con extensión Rmd. Archivo que se puede crear directamente desde el menú de Rstudio.

En este archivo es importante que se incluya un encabezado YAML como el que se muestra a continuación:

---
title: "Creación de un vignette de ejempo"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Creación de un vignette de ejempo}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

En este documento vamos a crear un vignette de ejemplo para mostrar como incluir este tipo de documentación en nuestro paquete. Para lo que se utiliza un archivo con la sintaxis de `rmarkdown`.

## Código de ejemplo

En nuestro documento podemos incluir código de ejemplo simplemente empleando tres comillas sencillas invertidas. Por ejemplo, se puede mostrar como sumar dos números con la función suma:

```{r}
library(rlane)
suma(1,2)
```

Como se puede ver en el ejemplo es necesario indicar el título del paquete, el formato de salida y las indicaciones para que se compile. En nuestro caso el formato de salida es HTML que es uno de los más populares.

Además de esto es necesario incluir la recomendación de los paquetes knitr rmarkdown en el archivo DESCRIPTION y una línea en la que se indique cómo crear las viñetas

VignetteBuilder: knitr

Creación de las viñetas

Posiblemente la manera más sencilla de complilaas viñetas sea con la función build_vignettes del paquete devtools. Es decir, escribiendo el comando

devtools::build_vignettes()

Lo que creará los archivos HTML con las viñetas en la carpeta inst/doc.

Conclusiones

En esta entrada hemos visto cómo incluir tutoriales en nuestros paquetes R con la inclusión de viñetas. Los tutoriales son clave para que los usuarios que tiene un primer contacto con nuestro paquete puedan empezar a trabajar de forma eficiente. Sin tener que buscar el toda la documentación los pasos a seguir para llegar a un resultado. La próxima semana finalizamos la serie con una entrada en las que explicaremos los medios que tenemos para distribuir el paquete.

Imagen de Peter H en Pixabay

Publicidad