TP3 : Automatiser la création de mon package R

BUT 3 - Domaines d’application

Auteur

Jean-Francois Rey

NoteObjectif du TP

Nous allons apprendre à automatiser des parties de la création d’un package R.

NotePourquoi ?

Pour gagner du temps par la suite et éviter de répéter des tâches qui peuvent être récurrentes et introduire des erreurs.

Prérequis

  • TP2
  • Disposer d’un projet package R sur Gitlab

Rappel

Note

Un package R c’est un répertoire normé qui contient à minima deux fichiers DESCRIPTION et NAMESAPCE ainsi que deux répertoires R/ et man/.
Il va vous permettre de capitaliser et réutiliser du code facilement.

AstuceDe la rigueur et de l’automatisation

La rigueur pour garder un package R normé et valide peut être très chronophage. Ici nous allons voir comment automatiser certaines parties afin de se simplifier la vie.

Important

Un membre du binôme doit faire le TP sur sa session. Au prochain TP vous changerez de membre.
Pensez à sauvegarder et à versionner votre travail aux étapes importantes.
Pensez bien à faire un pull avant de commencer à travailler.
Vous travaillez dans le répertoire versionné <monpackage>.

L’issue du TP

  • Créer une issue dans votre projet avec pour nom TP3.
  • Y ajouter ceci :
# TP3 : Automatiser la création de mon package R

## Tâches :   

1. [ ] Utiliser {Roxygen2}  
2. [ ] Implementer un test unitaire  
3. [ ] Créer un sireweb de mon package  
4. [ ] Automatiser en utilsant le CI/CD de GitLab  
etc.

## Version

Le commit correspondant au rendu final du TP : <clé SHA>
  • Dans l’issue principal du projet Rendu de notre projet associer cette dernière issue dans Linked Items
    • utiliser le numéro de l’issue ou son nom

Génération automatique de la Documentation…

NotePrincipe

Pour se faciliter la maintenance du package par la suite, on va automatiser la génération de la documentation ainsi que des fichiers DESCRIPTION et NAMESPACE.

Ceci grâce au package {roxygen2}.

Le principe est simple, les commentaires ajoutés dans notre code vont êtres lu et interprété par {roxygen2} pour générer automatiquement la documentation (le répertoire man/), etc.

Méta-données de mon package

Note

Pour générer le fichier DESCRIPTION et NAMESPACE.
la référence {roxygen2}

  • Créer un fichier dans le répertoire R au nom de <monpackage>-package.R : R/<monpackage>-package.R
  • Y ajouter et compléter ceci :
<monpackage>-package.R
#' @encoding UTF-8
#' @keywords internal
#' @title <comme dans le fichier DESCRIPTION>
#' @description <comme dans le fichier DESCRIPTION>
#' @aliases <monpackage>-package 
#'
#' @author <Nom Prénom \email{nom.prenom@@univ-avignon.fr}>
#'
#' Maintainer: <Prénom Nom \email{nom.prenom@@univ-avignon.fr}>
#' @docType package
#' @name <monpackage>-package
#' @details \tabular{ll}{
#'          Package: \tab <monpackage>\cr
#'          Type: \tab Package\cr
#'          Version: \tab 0.0.1\cr
#'          Date: \tab 2024-10-09\cr
#'          License: \tab GPL (>=3)\cr
#'          }
#' @details Ici plus de détail de ce que fait la package etc.  
#'
#' @keywords BUT3
#' @examples
#' \dontrun{
#' library("<monpackage>")
#' ma_fonction("test")
#' }
#' @md
#' @importFrom methods getPackageName
"_PACKAGE"

Documentation de mon package

Note

Pour générer la documentation de vos fonctions.
{roxygen2} référence

  • Ouvrir le fichier de votre première fonction (qui peut être R/<ma_fonction>.R)
  • Y ajouter et compléter ceci avant la déclaration de la fonction :
ma_premiere_fonction.R
#' @title ma premiere fonction
#'
#' @param monNom une chaine de character
#' @description
#' La description de ce que fait votre fonction
#'
#' @details
#' ici les détails important à connaitre
#'
#' @examples {
#' library(<monpackage>)
#' ma_fonction("les bleus 2")
#' }
#'
#' @return NULL
#' @export
  • Quels sont la signification des attributs précédé d’un @ dans cette exemple ?

Générer automatiquement la doc

  • Pour générer la documentation depuis la console R:
roxygen2::roxygenise()
Important

Vérifier les options de la méthode ?roxygenise

Il vous faudra peut être supprimer le fichier NAMESPACE et le .Rd (du TP précédent) pour que Roxygen2 puisse en créer de nouveau.
Attention DESCRIPTION n’est pas généré mais uniquement mis à jour.

NoteNom du fichier .Rd

Noter que le fichier .Rd créé porte le même nom de votre fonction.
Il ne peut avoir deux déclarations dans la même fonction dans un package. Vérifier qu’il n’y a pas de conflit avec un autre fichier .Rd créé précédemment. (Si c’est le cas supprimer l’ancienne version)

Pour générer la documentation à chaque fois que vous générez le package.
Aller dans le Menu “Build” -> “Configure Build Tools” -> “Built Tools” -> cocher Roxygen
Ceci va utiliser devtools::document() (qui appel roxygen2)

  • Vérifier que les fichiers DESCRIPTION, NAMESPACE et .Rd sont à jour.
  • Vérifier la validité de votre package et corriger en fonction des erreurs (Check, source, install).
Mise en gardeLes vignettes (pour information)

Un autre type de documentation est très utilisé : les vignettes.
Il s’agit de fichiers .Rmd contenus dans le dossier vignettes/ et qui sont construites au Build du package sous le format html et/ou pdf.
Comment faire une vignette

Ajout d’un test

Note

Ici nous allons effleurer la notion de test (test unitaire).
Le principe est d’effectuer automatiquement des tests sur les méthodes de votre package pour éviter l’introduction d’un nouveau bug et vérifier le bon comportement de celui-ci.

Important

Le check du package vérifie que le package est normé et valide. Il peut lancer les tests s’ils sont disponibles.
Le test du package vérifie uniquement vos tests.
Le package {testthat} permet de faire des tests.

  • Créer les repertoires tests/testthat/
  • Ajouter/compléter les champs dans le fichier DESCRIPTION
DESCRIPTION
Suggests: testthat (>= 3.0.0)
Config/testthat/edition: 3
  • Créer un fichier tests/testthat.R (oui dans le repertoire tests/) et y inclure ceci :
testthat.R
library(testthat)
library(<monpackage>)

test_check("<monpackage>")
  • Maintenant nous allons faire un test sur notre première fonction. Créer un fichier dans /tests/testthat/ nommé test-<nom_du_fichier_R_de_ma_fonction>.R
test_that("ma premiere fonction fonctionne", {
  expect_equal(ma_fonction("test"), NULL)
})
  • Il ne reste plus qu’a lancer le test (via le menu ou devtools::test()).
  • Observer le test effectué et le résultat du test
Important

Les fichiers de tests ont toujours le préfixe “test-”.
Référez vous à la documentation du package {testthat} pour ajouter de nouveaux tests.

Automatisation dans GitLab

Note

Comme vu en cours, il est possible d’automatiser des tâches (CI/CD) dans GitLab lors du commit/push. Il peut s’agir du packaging, des tests, de la compilation, etc.
La déclaration s’effectue dans le fichier .gitlab-ci.yml sous forme de jobs exécutes par les Runners GitLab. Les Runners GitLab sont des machines physiques ou virtuelles.

Sous Github ce concept s’appelle Actions.

Mise en gardeActivation du CI/CD

Dans le menu de votre projet GitLab, aller dans Settings -> General, puis visibility, et activer le CI/CD, sauver la configuration un peu plus bas.

Ensuite toujours dans le Settings -> CI/CD -> Runners activer les Shared Runners.

Nous allons configurer un fichier .gitlab-ci.yml pour qu’il construise et test notre package R.

  • Créer un fichier .gitlab-ci.yml et y inclure ceci (attention à l’indentation - vous pouvez changer la version de R utilisé dans rocker/verse:X.X.X)
.gitlab-ci.yml
# Ceci sont les étapes de votre pipeline : Les Stages
stages:
  - build
  - test

.linux-conf:
  variables:
    APT_PKGS: "texlive-latex-base texlive texlive-fonts-extra texlive-latex-recommended"
  before_script:
    - apt-get update
    - apt-get install -y --no-install-recommends ${APT_PKGS}
#    - Rscript -e 'install.packages(c("rmarkdown","roxygen2"), repos="https://cloud.r-project.org", ask=FALSE)'

"Construction du package":
  stage: build
  image: rocker/verse:4.3.1
  tags:
    - BUT
  script:
    - Rscript -e "roxygen2::roxygenize('.', roclets=c('rd', 'collate', 'namespace'))"
    - R CMD build .
  artifacts:
    paths:
      - ./*.tar.gz

"Check du package":
  stage: test
  image: rocker/verse:4.3.1
  extends: .linux-conf
  tags:
    - BUT
  script:
    - R CMD check --as-cran *.tar.gz
  dependencies:
    - "Construction du package"
  • Ajouter le nom de ce fichier dans le fichier .Rbuildignore .
  • Versionner (commit) et push.
  • Retourner sur la page du projet GitLab et cliquer dans le menu de gauche (build -> Pipelines)
  • Observer et cliquer sur le “runnings” et les différents jobs suivant leurs états (running, failed, passed,…)

La list des pipelines (CI/CD) de votre package.

Focus sur le pipeline en cours.

Les Runners GitLab sont de machines génériques qui ne contiennent pas forcement des packages R préinstallés.
Ici nous utilisons des images docker préconfigurées pour exécuter les jobs.
Vous pouvez installer les packages nécessaires à votre package en ajoutant ceci dans le job

before_script: 
  - R -e "install.packages(c("ggplot2"), repos="cloud.r-project.org")

Plus il y a de dépendances à des packages plus le CI/CD sera long car il doit les installer. (sauf si vous utilisez une image docker qui contient déjà les dépendances).
Exemples d’images Docker “officielles” disponibles sur le projet Rocker.

Important

Avec cette automatisation, à chaque mise à jour du package sur GitLab, il sera construit, testé, etc. Si vous ou vos collaborateurs introduisez une erreur elle sera détectée automatiquement. Cela va permettre aussi au source (et binaire), la documentation, etc. de votre package d’être disponibles et à jours.

Observer le job “Construction du package” une fois fini et le bouton Download (Télécharger) à droite ;-)

Créer le siteweb du package

Note

{pkgdown} permet de créer un site web static de la documentation de votre package (comme sur le lien précédent). Ce site web peut contenir toutes les informations que vous souhaitez donner à l’utilisateur, documentations, aides, tutoriels, etc.

Astuce

Gitlab (ainsi que GitHub) permet via le CI/CD de générer automatiquement le siteweb et de l’héberger pour le rendre accessible. L’hébergement se fait sur ce qu’on appel des Pages.
Cette fonctionnalité n’étant pas activée sur le GitLab de l’iut, nous allons faire autrement.

Configuration de pkgdown

Important

{pkgdown} va utiliser le fichier README.md pour générer la page d’accueil.
Compléter bien ce fichier.

  • Créer à la racine du package un fichier _pkgdown.yml
_pkgdown.yml
navbar:
  structure:
    left: [home, reference]
  • Ajouter dans le fichier .Rbuildignore le nom du fichier précédent (pour qu’il ne soit pas inclus dans votre package source)
  • Générer en local le siteweb
pkgdown::build_site()
  • ouvrir le fichier docs/index.html dans le navigateur web (normalement il s’ouvre automatiquement)
  • Supprimer le dossier docs ou ajouter le dans .gitignore et .Rbuildignore.

Automatisation et hébergement

Note

Ici nous automatisons la génération et l’hébergement du siteweb de notre package grâce au CI/CD de GtiLab.

  • Ajouter ce job dans le fichier .gitlab-ci.yml
AvertissementAjouter “deploy” dans la partie “stages” en haut du fichier 
.gitlab-ci.yml
stages:
  - build
  - test
  - deploy
.gitlab-ci.yml
# Le nouveau job à ajouter
pages:
  stage: deploy
  image: rocker/verse:4.4.1
  tags:
    - BUT
  script:
    - Rscript -e 'install.packages("pkgdown", repos="https://cloud.r-project.org")'
    - Rscript -e 'pkgdown::build_site(override = list(destination = "public"))'
  artifacts:
    paths:
      - public
  • Versionner (commit) et push (! attention de ne pas versionner les fichiers inutiles !)
  • RDV sur la page du projet GitLab
  • Vérifier le CI/CD (“build” -> “pipelines”)
  • Quand le CI/CD à fini, aller dans Menu de gauche -> “deploy” -> “pages” . Ici une URL vous permet d’accéder au siteweb de votre package. (!attention : le temps d’actualisation du site peut durer quelques minutes !)
AstuceVersion avec téléchargement du siteweb 
.gitlab-ci.yml
# Le nouveau job à ajouter
docs:
  stage: deploy
  image: rocker/verse:4.4.1
  tags:
    - BUT
  script:
    - Rscript -e 'install.packages("pkgdown", repos="https://cloud.r-project.org")'
    - Rscript -e 'pkgdown::build_site(override = list(destination = "siteweb"))'
  artifacts:
    paths:
      - siteweb
  • Versionner (commit) et push (! attention de ne pas versionner les fichiers inutiles !)
  • RDV sur la page du projet GitLab
  • Vérifier le CI/CD (“build” -> “pipelines”)
  • Quand le CI/CD à fini, aller sur le job docs . Dans le menu de droite vous pouvez télécharger l’artifacts construit (notre siteweb). Une fois téléchargé et dézippé vous pouvez ouvrir le fichier index.html dans votre navigateur.

Il est possible d’inclure les vignettes du package, ainsi que n’importe quel contenu important à l’utilisateur (par exemple le package source ou binaire).
Prenez exemple sur les sites déjà existants pour vous inspirer du contenu possible.
Ex : https://landsepi.pages-forge.inrae.fr/landsepi/
Pour custom {pkgdown}
Pour générer un logo de votre package.

Maintenant vous disposez d’un package R de base normé et valide. Il est testé, packagé et documenté automatiquement et toutes les informations utiles à l’utilisateur peuvent êtres accessibles via un site web.

- monpackage
  |- R
     |- ma_fonction.R
     |- ...
  |- DESCRIPTION
  |- NAMESPACE
  |- man
     |- ma_fonction.Rd
  |- .Rbuildignore
  |- .gitlab-ci.yml
  |- tests
     |- testthat.R
     |- testthat
         |- test-ma_fonction.R
  |- _pkgdown.yml
  |- README.md
  |- ...

Avant d’aller plus loin

  • Vérifier que vous avez suivie les consignes.
  • Vérifier que la documentation du package est à jour.
  • Vérifier que les Tests sont implémentés.
  • Vérifier que votre package est toujours normé et valide (Check, Test, Source, Install)
  • Vérifier que le dépôt GitLab de votre package est à jour.
  • Vérifier que le CI/CD fonctionne et est vert.
  • Vérifier que le siteweb est téléchargeable et fonctionnel. (l’ajouter en pièce joint de l’issue)

Questions:

  • Dans l’issue de ce TP (“TP3”).
  • Ajouter le message et la version du commit correspondant à ce TP
    (menu de gauche -> Code -> Commits) le commit correspond à la clé SHA.
  • Ajouter le Tags TP3 au commit
  • Répondez aux questions suivantes dans la description de l’issue :
    • Quels sont les avantages de l’automatisation de certaines parties de votre package ?
    • A quoi servent les tests sur un package ?
    • Comment fonctionne l’automatisation sous GitLab ? Comment l’activer ? Comment la configurer ?
    • Serez-vous en capacité de générer automatiquement la documentation de votre package ?
    • Définir simplement ce qu’est le CI/CD dans GitLab ?

Pour aller plus loin