Package pkgdown

Pour comprendre l’utilité du package pkgdown, le mieux est de tout simplement aller voir leur propre site de présentation du package créé avec le-dit package:

https://pkgdown.r-lib.org/

L’intérêt de pkgdown est qu’il s’appuie sur la structure classique d’un package R pour construire un site web (joli et discret) donnant une vitrine facile d’accès et d’exploration du package. Vous aurez par défaut:

• le nom du package et sa version actuelle
• un onglet “home”
• un onglet “Reference” contenant toutes les fonctions visibles de votre package. Chaque fonction a sa propre page web qui donne l’aide que vous avez créée dans le package via roxygen2, exemple compris.
• un onglet “Articles” contenant les vignettes que vous avez créées dans le package

Mise en place

Pour créer le site web de votre package, vous devez avoir:

• un package R développé complet (fonctions écrites, aide structurée écrite avec roxygen2, vignettes écrites et passant les étapes de check et de construction)
• déposé sur github ou gitlab (ou tout autre site web de versioning)
• un fichier README.md (souvent présent dès lors que vous avez déposé votre package sur le site de versioning)

Il suffit alors, après avoir installé le package pkgdown:

1. ouvrir le projet contenant votre package
2. dans la console R:

# Run once to configure your package to use pkgdown
usethis::use_pkgdown()

# Run to build the website
pkgdown::build_site()

Ces lignes de code génèrent le site web en déposant les fichiers nécessaires dans le répertoire /docs. Le README.md devient la page d’accueil, la documentation est extraite du répertoire /man et les vignettes du répertoire vignettes/. Il est possible de customiser le site en changeant les paramètres d’apparences, lire la doc pour voir les possibilités.

Les modifications se font principalement dans le fichier _pkgdown.yml.

A noter que les fichiers créés sont rajoutés au buildignore, le fichier de configuration de la construction du package. Cela veut dire que ces nouveaux fichiers n’impactent pas la construction du package.

Mise en ligne

Lorsque le site est créé, vous pouvez alors déposer ces nouveaux fichiers sur le repository de votre package sous github (par exemple): commit + push.

• Il faut alors modifier le paramétrage du repository sous github. Pour cela, connectez-vous à votre compte et cliquer sur Settings dans votre repository.
• Déroulez la page jusqu’au paragraphe Github pages
• Dans la section Sources, choisissez master branch dans la 1ere boite puis /docs dans la 2e. Ceci indique à github d’afficher les fichiers web contenus dans le répertoire /docs de la branche master.

Github crée alors une url spécifique à votre compte et votre repository sous la forme:

https://MyID.github.io/myPackageName

Références

1. https://pkgdown.r-lib.org/
2. https://cran.r-project.org/web/packages/pkgdown/index.html
3. https://usethis.r-lib.org/
4. https://github.com/

Session Informations

## R version 4.1.2 (2021-11-01)
## Platform: x86_64-w64-mingw32/x64 (64-bit)
## Running under: Windows 10 x64 (build 19044)
## 
## Matrix products: default
## 
## locale:
## [1] LC_COLLATE=French_France.1252  LC_CTYPE=French_France.1252   
## [3] LC_MONETARY=French_France.1252 LC_NUMERIC=C                  
## [5] LC_TIME=French_France.1252    
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## loaded via a namespace (and not attached):
##  [1] bookdown_0.24   digest_0.6.29   R6_2.5.1        jsonlite_1.8.0 
##  [5] magrittr_2.0.1  evaluate_0.14   blogdown_1.7    stringi_1.7.6  
##  [9] rlang_0.4.12    jquerylib_0.1.4 bslib_0.3.1     rmarkdown_2.11 
## [13] tools_4.1.2     stringr_1.4.0   xfun_0.29       yaml_2.2.1     
## [17] fastmap_1.1.0   compiler_4.1.2  htmltools_0.5.2 knitr_1.37     
## [21] sass_0.4.0