8. Compartir el paquete

⏱ Enseñanza: 5 minutos · Ejercicios: 7 minutos

Preguntas

  • ¿Cómo presento mi paquete?
  • ¿Cómo lo instalo y lo uso desde otro proyecto?
  • ¿Cómo lo comparto con otras personas?
  • ¿Qué sigue después de este taller?

Objetivos

  • Crear un README con usethis::use_readme_rmd().
  • Instalar el paquete con devtools::install() y usarlo desde otra sesión.
  • Conocer cómo publicar el paquete en GitHub.
  • Conocer recursos para seguir aprendiendo.

El README: la puerta de entrada

El README es lo primero que ve alguien que encuentra tu paquete. Tiene que contar:

  • qué hace el paquete, sin jerga;
  • cómo se instala;
  • un ejemplo de uso;
  • cómo contribuir o pedir ayuda.

💻 En vivo

usethis::use_readme_rmd()

Es un archivo R Markdown, así que el ejemplo se ejecuta y muestra el resultado real. Escribimos y después lo construimos:

devtools::build_readme()

Esto genera README.md, que es el que muestra GitHub. Editá siempre el .Rmd; el .md se genera solo.

Instalar el paquete

Hasta ahora usamos load_all(), que solo funciona adentro del proyecto del paquete. Para usarlo desde cualquier proyecto, hay que instalarlo:

💻 En vivo

devtools::install()

En RStudio, también con el botón Install de la pestaña Build (Ctrl + Shift + B).

Y ahora, en otra sesión de R, como cualquier otro paquete:

library(dichosos)
dicho_al_azar(pais = "Perú")
?buscar_dicho

Compartir en GitHub

En el taller lo mostramos sin hacerlo; el desafío 8.2 es para que lo pruebes en casa.

Si el paquete está en GitHub, cualquier persona lo puede instalar con una línea. usethis también ayuda con esto:

usethis::use_git()      # crea el repositorio local y hace el primer commit
usethis::use_github()   # crea el repositorio en GitHub y sube todo

Y para instalarlo:

pak::pak("tu-usuario/dichosos")

Además, R-universe puede construir tu paquete y ofrecerlo ya compilado, para que nadie tenga que instalarlo desde el código fuente.

El recorrido completo

  1. pak::pkg_name_check()
  2. usethis::create_package()
  3. usethis::use_mit_license()
  4. usethis::use_r() y devtools::load_all()
  5. Esqueleto de roxygen2 y devtools::document()
  6. usethis::use_data_raw() y usethis::use_data()
  7. usethis::use_package()
  8. usethis::use_testthat(), usethis::use_test() y devtools::test()
  9. usethis::use_readme_rmd() y devtools::install()
  10. Y siempre: devtools::check()

¿Qué sigue?

Lo que vimos hoy es la base. Algunos próximos pasos:

  • Un sitio web para tu paquete con pkgdown: usethis::use_pkgdown() y pkgdown::build_site().
  • Viñetas, documentos largos que cuentan cómo usar el paquete: usethis::use_vignette().
  • Integración continua: que GitHub corra check() en Windows, macOS y Linux cada vez que subís cambios, con usethis::use_github_action("check-standard").
  • Abrir tu paquete a contribuciones: usethis::use_code_of_conduct() y usethis::use_tidy_contributing().

Y para seguir aprendiendo, en castellano:

En inglés, el libro de referencia es R Packages, de Hadley Wickham y Jennifer Bryan.

Desafío 8.1: Un README y a instalar 10 minutos

  1. Creá el README con usethis::use_readme_rmd().
  2. Escribí una oración sobre qué hace el paquete y un ejemplo con dicho_al_azar().
  3. Construilo con devtools::build_readme().
  4. Instalá el paquete con devtools::install().
  5. Reiniciá R, o mejor, abrí otro proyecto, y escribí library(dichosos) y dicho_al_azar().

¡Si te salió un dicho, ya tenés tu primer paquete instalado! 🎉

# dichosos

¡Dichos y expresiones populares de América Latina, directo a tu consola de R!

## Ejemplo


::: {.cell}

```{.r .cell-code}
library(dichosos)
dicho_al_azar(pais = "Chile")
```
:::
devtools::build_readme()
devtools::install()

En otra sesión:

library(dichosos)
dicho_al_azar()

Desafío 8.2 (opcional, si tenés GitHub configurado): Al mundo 5 minutos

  1. usethis::use_git() y aceptá hacer el primer commit.
  2. usethis::use_github().
  3. Pegá el enlace a tu repositorio en el documento colaborativo.
  4. Instalá el paquete de otra persona del taller con pak::pak("usuario/dichosos"). ¿Qué dichos agregó?

Desafío 8.3: Para cerrar 3 minutos

En el documento colaborativo (o en tus notas adhesivas):

  • Para mantener: una cosa que aprendiste hoy y te gustó.
  • Para mejorar: una cosa que mejorarías del taller, o que todavía no te quedó clara.

Y una más: ¿qué código tuyo vas a convertir en paquete?

Puntos clave

  • El README presenta el paquete: qué hace, cómo se instala y un ejemplo.
  • devtools::install() instala el paquete para usarlo desde cualquier proyecto.
  • Con el paquete en GitHub, cualquier persona lo instala con pak::pak("usuario/paquete").
  • Ya sabés crear un paquete. Ahora, ¿qué código tuyo vas a empaquetar?