‘fusen’ v0.3: De meilleurs modèles de projets, des fonctions groupées et de nombreuses autres améliorations

{fusen} gagne en maturité ! La v0.3 est un grosse refonte pour une expérience plus fluide, du débutant au développeur avancé. Créer un package entièrement documenté et testé n’a jamais été aussi facile et agréable. Vivez pleinement l’expérience du “Rmd first”.

Au départ, j’ai imaginé {fusen} pour aider les débutants à commencer à construire des packages R. En suivant la méthode “Rmd first”, je suis convaincu que la construction d’un package est accessible à tous. Avec {fusen}, c’est encore plus vrai.
Cependant, je suis moi-même surpris de l’opportunité donnée par {fusen} pour m’aider, je peux dire un utilisateur avancé de R, à construire des packages correctement documentés et testés, avec facilité. Cela réduit ma charge mentale pour de nombreuses tâches pendant le développement. Et mes collègues de ThinkR sont encore plus convaincus que moi!

Si vous êtes déjà un⋅e développeur⋅se R et que vous envisagez de créer un nouveau package, ou d’ajouter une nouvelle fonctionnalité à votre package existant, essayez-le. Vous me direz plus tard si cela vous permet de les construire mieux documentés et testés.

Installer {fusen} depuis CRAN ou r-universe

Vous pouvez installer la version en cours du CRAN :

install.packages("fusen")

La documentation complète pour la version du CRAN est ici : https://thinkr-open.github.io/fusen/

Vous pouvez installer la version en développement de {fusen} depuis GitHub :

install.packages("fusen", 
                 repos = "https://thinkr-open.r-universe.dev")

La documentation complète pour la version de développement est là: https://thinkr-open.github.io/fusen/dev/

Rencontrer le modèle de projet {fusen}

{fusen} consiste à séparer et à nommer correctement des chunks

• Créer un nouveau répertoire / nouveau projet avec
  • Template RStudio : Fichier > Nouveau projet > Nouveau répertoire > Package utilisant {fusen}
    
• Choisissez le template
  • Choisissez le template teaching la première fois pour voir comment {fusen} fonctionne,
  • Choisissez le template complet la seconde fois pour répondre à la plupart de vos questions.
    
• Ouvrez le fichier “dev/flat_teaching.Rmd” pour commencer à configurer le package
• Dans ce modèle Rmd plat, exécutez le premier chunks nommé description demandant de décrire votre paquet et de le licencier
  • Les deux lignes de code ressemblent à ceci :

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

• Rédigez votre analyse et vos fonctionnalités en suivant le modèle Rmd
  • Vous les développerez probablement avec quelques exemples et tests
  • Pour la première fois, vous pouvez laisser le code tel quel, c’est déjà le contenu d’un paquet fonctionnel
• Exécutez le code suivant pour transformer le Rmd plat en paquet gonflé.
  • Cela ouvrira la vignette créée et checkera le package

fusen::inflate(
  flat_file = "dev/flat_teaching.Rmd",
  vignette_name = "Get started",
  check = TRUE
)

C’est tout ! Vous avez construit un package ! Un paquet documenté et testé !

Créer un package {fusen} en ligne de commande

• create_fusen() crée un projet prêt à être gonflé

library(fusen)
## Create a new project
dummypackage <- tempfile(pattern = "dummy")
# Create the template
dev_files <- create_fusen(dummypackage, template = "full", open = FALSE)
# Get the flat Rmd file template
flat_file <- dev_files[grepl("flat_", dev_files)]
# Fill description
fill_description(pkg = dummypackage, fields = list(Title = "Dummy Package"))
# Inflate the package
inflate(
  pkg = dummypackage, 
  flat_file = flat_file,
  vignette_name = "Get started", check = TRUE,
  open_vignette = FALSE)

Ajouter de nouveaux templates plats pré-remplis pour votre fonction

add_flat_template() remplace add_dev_history() pour ajouter un nouveau template plat dans votre répertoire “dev/”.

• Utilisez add_flat_template("add") pour ajouter un nouveau template vide avec les trois chunks function, example et test.
• Utilisez add_flat_template("add", flat_name = "my_func") pour ajouter un template pré-rempli pour votre fonction nommée my_func().

Il y a aussi un Addin RStudio nommé “Add {fusen} chunks” qui ajoutera l’ensemble des trois chunks, pré-remplis avec le nom de votre fonction, dans le fichier Rmd en cours.

## my_func
```{r function-my_func}
#' Title
#' 
#' Description
#' 
#' @return
#' 
#' @export
my_func <- function(){
}
```
```{r example-my_func}
my_func()
```
```{r tests-my_func}
test_that("my_func works", {
  expect_true(inherits(my_func, "function")) 
})
```

Notez que les templates sont maintenant nommés flat_*.Rmd car nous gonflons un papier plat en un joli paquet. Le fichier dev_history.Rmd existe toujours pour stocker tous les outils transverses comme les fonctions de {usethis} et de {devtools}.

Regroupement des fonctions sous le même fichier R après inflate()

{fusen} gonfle un template Rmd plat en plusieurs fichiers “.R” dans les répertoires “R/” et “tests/”. Bien que le développement ne soit censé avoir lieu que dans le template plat, vous pouvez souhaiter une organisation plus concise de ces répertoires.

La version 0.3 permet de regrouper certaines fonctions dans les mêmes fichiers “R/” et “tests/” après le gonflage.

Les fonctions sont regroupées dans le même fichier R et le même fichier de test :

• si elles sont sous les mêmes titres (niveau 1 + niveau 2) dans le Rmd.
• si elles ont la même étiquette roxygen @rdname.
• si elles ont la même étiquette roxygen @filename (reconnu seulement par ‘fusen’)
• si le chunk de la fonction a l’option {r function-my_func, filename = "my_filename"}.

Découvrez plus d’infos dans la nouvelle vignette Tips & Tricks

Trucs et astuces

J’ai rassemblé de nombreux conseils et astuces dans une nouvelle vignette :
https://thinkr-open.github.io/fusen/articles/tips-and-tricks.html

• Puis-je tricoter le contenu d’un template plat ?
• Comment déclarer les paquets avec library() pour la future vignette ?
• Comment inclure des exemples qui ne peuvent pas être exécutés ?
• Documentez vos jeux de données internes dans un chunk de fonction comme d’habitude.
• Comment ignorer certains chunks ?
• Comment obtenir un modèle pré-rempli pour un nom de fonction spécifique ?
• Comment gonfler plusieurs fichiers plats ?
• Comment stocker plusieurs fonctions dans un fichier R unique ?

Toutes les autres améliorations décrites dans NEWS

Changements de rupture

• add_flat_template() superseeds add_dev_history() avec des possibilités plus avancées.
• add_dev_history() est déprécié.
• Le nom de la vignette à créer est maintenant défini avec inflate(vignette_name = "Get started") au lieu de name.
• Le nom du fichier plat à gonfler est maintenant défini avec inflate(flat_file = "dev/flat_full.Rmd") au lieu de rmd.

Changements majeurs

• Regroupement des fonctions sous un même fichier
• La vérification incluse utilise maintenant devtools::check() au lieu de rcmdcheck().
• Eviter de créer une vignette avec inflate(vignette_name = NA).
• Décider d’ouvrir ou non la vignette lors du gonflage avec inflate(open_vignette = FALSE).
• Améliorer la documentation incluse dans les modèles plats pour refléter les changements dans l’utilisation du fichier dev_history.
• Ajout d’un addiciel Rstudio pour insérer un nouveau modèle plat.
• Addin Rstudio pour insérer des chunks pour une nouvelle fonction (@ColinFay)
• Traitement de \dontrun{} dans les chunks d’exemple
• Autoriser les noms courts pour les chunks : dev, fun, ex, test…
• create_fusen() pour créer un projet {fusen} depuis la ligne de commande ou avec le nouveau projet RStudio (@ALanguillaume)
• Ajouter “ne pas éditer à la main” dans les fichiers générés

Changements mineurs

• add_flat_template() utilise le flat_name pour pré-remplir le template avec le premier nom de fonction.
• Corriger la création du fichier de fonctions .onLoad
• Autorise R6Class() dans les chunks function.
• Fixe le gonflement des chunks de fonctions avec des données ou de la documentation de paquet seulement.
• Fixe le gonflement avec des chunks de fonctions vides
• Correction du nom de fichier à gonfler dans les modèles avec les nouveaux appels de add_dev_history() (@Cervangirard)
• Le nom de la vignette par défaut est maintenant “Get started” créant “vignettes/get-started.Rmd”
• Tous les fichiers ouverts sont sauvegardés quand on utilise inflate() où {rstudioapi} fonctionne
• Demande de redémarrage de RStudio après le premier gonflage