{fusen}: Créer un package à partir d’un simple fichier RMarkdown

Vous savez comment construire un Rmardown, on vous a dit ou vous aimeriez mettre votre travail dans un package R, mais vous pensez que c’est trop de travail ? Vous ne comprenez pas où mettre quoi et quand ? Et si écrire un Rmd était la même chose que d’écrire un package ? Suivez la méthode « Rmd-first » et laissez {fusen} vous guidez par {fusen} pour créer un package documenté et testé, pour assurer la pérennité et le partage de vos travaux.

Vous êtes à un RMarkdown de construire un package !

• Installer {fusen} depuis GitHub (https://thinkr-open.github.io/fusen) :

remotes::install_github("ThinkR-open/fusen")

• Créer et ouvrir un nouveau répertoire ou un nouveau projet RStudio
  • Choisir un nom de package / dossier comme my.package par exemple
• Exécuter le code suivant directement dans la console pour ajouter le modèle de Rmd à l’intérieur du projet et l’ouvrir

dev_file <- fusen::add_dev_history(open = TRUE)

• Dans le modèle Rmd, exécuter les premiers chunks qui demande de décrire le package et de lui mettre une licence
  • Les lignes de code ressemblent à celles-ci :

fill_description(fields = list(Title = "My Awesome Package"))
usethis::use_mit_license("Sébastien Rochette")

• Suivez le guide pour créer votre analyse et vos fonctionnalités
  • Vous développez probablement avec quelques exemples et tests
  • Pour la première fois, vous pouvez laisser le code du Rmd tel quel, c’est déjà le contenu d’un package qui marche
• Exécuter le code suivant pour transformer ce Rmd en package
  • Cela va ouvrir la vignette de votre package

fusen::inflate(rmd = dev_file, name = "my-functionnality", check = TRUE)

C’est tout ! Vous avez créé un package !

Testons-le maintenant :

• Installer localement le package

remotes::install_local()

• Redémarrer votre session R pour vider l’environnement
  • Vous pouvez redémarrer votre session RStudio pour faire apparaître l’onglet ‘Build’ dans l’interface
• Tester le bon fonctionnement de son package

my.package::my_median(1:12)

• Tester que le documentation est correctement construite en créant un site web dédié

# Build {pkgdown} to test it
pkgdown::build_site()
# > See references and articles
# Hide output from package and git
usethis::use_build_ignore("docs")
usethis::use_git_ignore("docs")

À qui s’adresse {fusen} ?

Lorsque vous rédigez un fichier RMarkdown (ou une vignette), vous créez une documentation pour votre analyse (ou package). A l’intérieur, vous écrivez quelques fonctions, vous testez vos fonctions avec des exemples et vous écrivez probablement des tests unitaires pour vérifier les résultats. C’est encore plus vrai si vous suivez ce guide : ‘Rmd first’ : Quand le développement comme par la documentation.
Ensuite, vous devez déplacer vos fonctions et vos scripts au bon endroit. Laissez {fusen} faire cela pour vous !

{fusen} s’adresse d’abord aux personnes qui n’ont jamais écrit de package auparavant mais qui savent comment écrire un fichier RMarkdown. Comprendre l’infrastructure d’un package et la régler correctement peut être effrayant. {fusen} peut vous aider à faire les premiers pas.

{fusen} s’adresse également aux développeurs plus avancés qui en ont assez de passer d’un fichier R à l’autre, de passer d’un fichier de test à l’autre, de passer d’une vignette à l’autre. En particulier, lorsqu’on change les arguments d’une fonction, il faut changer les exemples, les tests unitaires à plusieurs endroits. Ici, vous pouvez le faire à un seul endroit. Pas de risque d’en oublier un.

Pourquoi ce package s’appelle-t-il « fusen » ?

Un fusen est un origami. C’est un morceau de papier que l’on plie d’une manière spécifique pour qu’à la fin, on puisse le gonfler comme par magie pour laisser apparaître une jolie boîte.

De même, le package {fusen} utilise une page de RMarkdown, que vous remplissez d’une manière spécifique de sorte qu’à la fin, vous pouvez magiquement le gonfler (inflate()) pour laisser apparaître un joli package.

Le modèle RMarkdown

• Suivez le modèle "dev/dev_history.Rmd" pour écrire votre documentation, construire vos fonctions et tester vos exemples.
  • Le chunk nommé fonction reçoit le code d’une fonction
  • Le chunk nommé example récupère le code pour les exemples d’utilisation de la fonction. Il sera utilisé pour la fonction @examples et sera conservé pour la vignette
  • Un chunk nommé tests récupère le code pour les tests unitaires
  • Le chunk appelé developpement récupère le code pour le développement, généralement utilisé une seule fois comme les fonctions de {usethis}.
• Gonflez le modèle pour le transformer en un package avec des fonctions, des tests unitaires et le Rmd actuel transformé en vignette. Et vérifiez (check()).

Notez que le modèle "dev_history.Rmd" est un exemple fonctionnel.
Notez également que le cœur de {fusen} est créé à partir du modèle "dev_history.Rmd" disponible dans son dépôt GitHub : https://github.com/ThinkR-open/fusen/blob/master/dev/dev_history.Rmd

Remerciements

• Merci à Deemah qui m’a demandé d’aller plus loin dans le “Rmd first” après ma présentation à use’R 2019 à Toulouse : “La méthode”Rmd first » : quand les projets commencent par la documentation » (Vidéo sur Youtube : https://youtu.be/cB1BCxFbhtk).
• Merci à @rundel et son package {parsermd} qui m’ont aidé à me remettre dans ce projet avec facilité : https://github.com/rundel/parsermd