Créer un livre ou document avec bookdown
Travailler avec le format Rmarkdown est devenu pour moi une évidence, je l’utilise systématiquement !
Mais depuis quelque temps, j’entends parler du package `bookdown` qui permet de passer à l’étape suivante en créant des livres, ou des rapports techniques, dans tous les cas des documents constitués de plusieurs chapitres, rédigés en RMarkdown.
C’est d’ailleurs avec `bookdown` qu’ont été créé, en autres, le livre R for data science de Hadley Wickham et Garrett Grolemund, ou encore le livre Text Mining de Julia Silge and David Robinson, ou encore la documentation du package caret de Max Kuhn, et bien évidemment le livre dédié au package `bookdown` “bookdown: Authoring Books and Technical Documents with R Markdow” de Yihui Xie !
J’avais très envie d’essayer ce package, mais comme j’appréhende toujours un peu les nouveautés et les choses techniques, ça me faisait un peu peur ! Et puis très récemment, j’ai dû créer un support de cours pour une formation, alors c’était l’occasion ou jamais d’essayer de créer un document global avec `bookdown`. Et ben, j’ai réussi ! Et assez facilement en fait ! Alors évidemment, je ne maîtrise pas (encore) bookdown dans sa globalité, il me reste plein de choses à approfondir, à tester et à améliorer, mais c’est un vrai bon début.
J’ai donc eu envie d’écrire cet article sur la création d’un document avec bookdown pour vous montrer comment faire en pas à pas, et pour que vous vous lanciez vous aussi, parce que ça vaut vraiment le coup !
Installer le package bookdown
Rien de compliqué
Créer un projet R de type book
Pour cela, dans R Studio : File –> New project –> New Directory
–> Book Project using bookdown :
Choisissez où placer ce projet, et donnez lui un nom. Ici, j’ai créé un projet “mon_premier_super_livre” dans le dossier “Mes_Livres” qui est dans “Mes documents”.
En allant dans le dossier “Mes_Livres” je retrouve bien un sous-dossier “mon_premier_super_livre” :
Ce processus crée en réalité un projet exemple. En l’ouvrant, on peut voir qu’un certain nombre d’éléments ont été ajoutés, notamment des fichiers .rmd qui correspondent aux différents chapitres d’un livre exemple, ainsi qu’ un projet R (ici nommé mon_super_premier_livre).
Le bouton "Build block"
En ouvrant le projet R, on peut voir un nouveau bouton “Build Block” qui va permettre de construire le livre :
Lorsqu’on clique dessus, les différents fichiers.Rmd, qui ont été générés automatiquement à l’étape précédente, sont assemblés, et la version html du livre apparaît dans le Viewer de R Studio. :
La première page du livre correspond au fichier index.Rmd:
Ensuite, viennent les différents chapitres qui correspondent aux fichiers .rmd qui commencent par “01-“, “02-“, etc…, ici : “01-intro”, “02-literature”, “03-method” etc…
Ensuite, viennent les différents chapitres qui correspondent aux fichiers .rmd qui commencent par “01-“, “02-“, etc…, ici : “01-intro”, “02-literature”, “03-method” etc…
Modifier l'exemple
Pour créer votre premier document, ou livre, il suffit de modifier les fichiers existants.
Le fichier index.Rmd
Ici, j’ai changé le titre, l’auteur et la description, et j’ai supprimé tout le reste, car ici je ne souhaite pas de chapitre “préambule”.
Les fichiers chapitres
Les noms
Il s’agit des fichiers commençant par 01-....Rmd, 02-....Rmd , 03-....Rmd.
Par défaut `bookdown` compile tous les fichiers `.Rmd` présents dans le working directory du projet dans l’ordre alphabétique de leur nom. Il est donc pratique de les nommer en commençant par un numéro. Pour soustraire un fichier `.rmd` à l’assemblage, il suffit de commencer son nom par `_` (tiret bas, *underscore*).
Ici, pour coller à mon projet de support de cours, j’ai modifié les noms originaux :
01-intro.Rmd02-literature.Rmd03-method.Rmd- etc…
en :
01-workflow.Rmd02-imortation.Rmd03-manipulation_avec_dplyr.Rmd04-visualisation_avec_ggplot2.Rmd
Le contenu
Il est important de noter que les fichiers .Rmd des chapitres:
- ne possèdent pas d’en-tête yaml
- commencent par le titre du chapitre, précédé par un
# - ne doivent pas contenir de numérotation de paragraphe et sous-paragraphes (cela est directement géré par
bookdown).
Voici un exemple :
Et le rendu avec la première page du livre à gauche et la première page du chapitre 4 à droite :
Ajouter les dossiers nécessaires
Par exemple, j’avais un dossier “data” (où je place les jeux de données que vais importer), et un dossier “img” qui contient des images que j’ai besoin d’insérer dans mon document. J’ai placé ces deux dossiers, comme habituellement, dans le working directory du projet :
Récupérer le document assemblé
C’est bien beau de voir le document dans le viewer, mais en avoir une version pdf ou epub, c’est mieux !
Pour cela, il suffit d’aller dans le dossier “_book” :
Puis :
Comment je me suis organisée ?
En réalité, comme je n’étais pas certaine de réussir à compiler mon document, j’ai d’abord écrit mes chapitres en R markdown de façon traditionnelle, c’est-à-dire de façon à générer un rapport dynamique par chapitre. En me disant, au cas où je n’arrive pas à faire un seul grand document, ben j’aurais toujours les chapitres sous forme de documents word ou pdf séparés. Ces fichiers R markdown avaient donc un en-tête yaml et une numérotation pour les paragraphes et sous paragraphes. J’ai régulièrement généré, en html, un rapport dynamique des ces chapitres aucours de leur rédaction, pour vérifier, via le viewer, le rendu, la mise en page, et corriger les fautes de frappes et d’orthographes (enfin celles que je voyais 😉 ).Quand j’ai estimé que tous les chapitres étaient prêts, j’ai copié le premier chapitre en .Rmd dans mon R projet bookdown. Puis :
- je l’ai renommé “01-workflow”
- j’ai supprimé l’entête yaml
- j’ai ajouté le titre
- j’ai supprimé la numérotation des paragraphes et sous-paragraphes
- j’ai compilé le livre
- j’ai vérifié que tout était OK
- j’ai recommencé toutes ces étapes avec le fichier du chapitre 2, puis
de chapitre 3, etc…un par un.
Problèmes et limites rencontrés
Redondances des chunks setup
Tous mes fichiers de chapitres possédaient un chunck set up comme celui ci :
Cela a généré un message d’erreur et un arrêt de la compilation du livre. Je ne l’ai gardé que pour le premier chapitre.
La taille des images
Dans le document final pdf (qui est le format qui m’intéressait en priorité), certaines images importées dépassaient la largeur de la page. J’ai ajouté l’option out.fig="75%" ou moins, dans les chunks concernés :
Un conflit de package
J’ai rencontré un problème de conflit entre les packages `dplyr` et `Rmisc`, la fonction `select()` ne fonctionnait plus, j’ai dû ajouter `dplyr::` devant chacune des fonctions `select()`.
Dans le livre “bookdown: Authoring Books and Technical Documents with R Markdown“, Yihui Xie explique que le livre peut être compilé selon deux procédures :
- une procédure “Merge and Knit” (M-K) qui consiste à assembler tous les chapitres et à kniter l’assemblage pour obtenir la version pdf. Dans cette situation tous les chunks de tous les chapitres sont exécutés dans la même session, ce qui peut provoquer des conflits. C’est la procédure employée par défaut.
- une procédure “Knit and Merge” (K-M) dans laquelle les chunks des différents chapitres sont exécutés dans des sessions différentes (ce qui limite les conflits).
Ce problème de conflit est intervenu lorsque j’ai ajouté un de mes derniers chapitres, alors je n’ai pas voulu prendre le risque d’avoir d’autres erreurs en changeant la procédure par défaut. Je suis donc restée en M-K.
Table des matières
La table des matières générée ne contenait que le premier niveau des paragraphes. Je l’ai laissé comme cela.
Les références bibliographiques
Il est possible d’intégrer une liste de références bibliographique, mais je n’en avais pas vraiment besoin alors je ne l’ai pas encore testé.
Obtenir un document au format word (docx)
Initialement, je désirai seulement obtenir un document au format pdf, ce que j’ai eu. Mais par la suite, je me suis demandé comment faire pour obtenir un document au format docx plutôt que pdf, ou en plus du pdf, et pour l’instant, je n’ai pas creusé, mais à priori c’est possible.
Ressources
Outre le livre “bookdown: Authoring Books and Technical Documents with R Markdown“, pour aller plus loin dans l’amélioration de vos documents, vous pouvez également consulter l’article “How to self publish a book: customizing Bookdown” de Pablo casas
J’espère que cet article vous aura convaincu qu’il est relativement facile de réaliser un document ou un livre constitué de plusieurs chapitres avec le package `bookdown`. Et que de ce fait, il vous aura donné envie de franchir le pas, pour aller plus loin que le simple rapport d’analyse créé en R markdown. Personnellement, je suis convaincue par ce package et cette façon de travailler. Il ne me viendrait plus à l’idée de rédiger un cours, ou une note technique sous Word !
Et vous, que pensez-vous de bookdown ?
Si cet article vous a plu, ou vous a été utile, et si vous le souhaitez, vous pouvez soutenir ce blog en faisant un don sur sa page Tipeee 🙏
Crédit photo : open clipart-vectors
Merci Claire pour cet article ; ce serait cool de pouvoir en faire une version imprimable pour la garder quelque part ou la diffuser (à des étudiants par exemple) sans forcément avoir besoin de ce connecter sur ton blog via Internet. Possible ?
Merci Claire. Très enrichissant cet article. Je viens d’apprendre quelque chose de nouveau R
Merci Claire pour ce super tutoriel