Rédiger avec bookdown : pourquoi ? comment ?

rediger-avec-bookdown

{bookdown} c’est quoi ? C’est un package R destiné à l’écriture de rapports et de livres numériques. Il existe depuis 2016 et est développé par l’un des membres de la dream team de chez RStudio : Yihui Xie. Vous connaissez sûrement son nom si vous êtes adeptes de Shiny, leaflet, R Markdown, DT, … Un coup d’oeil à son dépôt Github et vous vous rendrez vite compte de son apport important à la communauté.

{bookdown}, à quoi ça sert ?

Ok, arrêtons de jouer aux groupies et revenons-en à nos moutons. {bookdown} est un package R qui permet de créer des livres via R, de la même manière que nous créons des documents à l’aide de R Markdown. Il s’appuie d’ailleurs sur {rmarkdown}, hérite donc de la simplicité de la syntaxe markdown, et permet aussi plusieurs formats de sortie : html, pdf, Word. Le style Gitbook ou le pdf_book par dessus et le tour est joué, vous avez un beau livre numéroté avec accès aux chapitres et tout le toutim. Regardons maintenant quelques exemples :

En fait de livres, {bookdown} peut être utilisé simplement pour créer un livre numérique qui ne sera constitué que de quelques fichiers RMarkdown que l’on souhaite lire linéairement en une séquence, ou encore pour mettre en page sa prise de notes de cours, rédiger sa thèse, le rapport de ce projet que l’on vient de terminer, … Écrire un livre numérique avec {bookdown} a également de nombreux avantages :

  • On ne se soucie pas de la composition du document
  • Cela nous évite d’utiliser le langage LateX directement, has been et relativement compliqué quand on ne connait pas
  • La collaboration autour de la rédaction s’en trouve largement simplifiée
  • Les multiples formats de sorties possibles (PDF, HTML, Word)
  • On peut également intégrer du contenu dynamique et interactif aux livre HTML

Mais ça a l’air trop cool ! On fait comment ?

bookdown engineering-shiny.org

gitbook HTML : « Engineering Production-Grade Shiny Apps » rédigé avec {bookdown}

Votre premier bookdown

Avant de commencer

Ne mettons pas la charrue avant les bœufs. Avant de pouvoir écrire notre book, plusieurs choses vont être nécessaires.

Déjà, on commence par installer le package. La version stable du CRAN :

install.packages("bookdown")
library(bookdown)

ou la version en développement sur GitHub :

devtools::install_github('rstudio/bookdown')
library(bookdown)

Nous avons également besoin d’une distribution de packages LaTeX pour la création de PDF, et pour ce faire, on télécharge le package {tinytext} et on l’installe (attention, cela peut prendre pas mal de temps) :

install.packages('tinytex')
tinytex::install_tinytex()

Il vous faudra ensuite connaître les bases de RMarkdown, je vous conseille vivement de visiter cette page : https://rmarkdown.rstudio.com/ et de consulter autant qu’il le faudra la cheatsheet suivante : https://rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf

Une fois les bases acquises, venons-en au fait.

Création du nouveau book

La création d’un book commence par la création d’un nouveau projet. Dans RStudio : File -> New Project… -> New Directory. L’installation du package {bookdown} a introduit une nouvelle ligne à la liste de choix de type de projet :

Ok, notre nouveau projet est créé. Regardons de plus près les fichiers automatiquement inclus :

--- 
title: "A Minimal Book Example"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib, packages.bib]
biblio-style: apalike
link-citations: yes
description: "This is a minimal example of using the bookdown package to write a book. The output format for this example is bookdown::gitbook."
---
  • Un livre contient typiquement plusieurs chapitres. Ici, chaque fichier RMarkdown constitue un chapitre : 01-intro.Rmd, 02-literature.Rmd, etc. Par défaut, tous les RMarkdown sont pris en compte, dans l’ordre alphanumérique, excepté le fichier index.Rmd qui passe toujours en premier. Chaque fichier .Rmd doit commencer par un titre de niveau avec le nom du chapitre. Par exemple, le fichier 02-literature.Rmd commence par :
# Literature
  • Le fichier _bookdown.yml est un fichier au format YAML contenant les métadonnées de notre livre. Si on souhaite faire apparaître seulement certains RMarkdown, ou dans un ordre différent, on l’indique dans ce fichier de la façon suivante :
rmd_files: ["index.Rmd", "03-method.Rmd", "01-intro.Rmd"]
  • Le fichier _output.yml permet de définir les caractéristiques des formats de sortie. Vous avez noté que lorsqu’on rédige un fichier RMarkdown, on se pré-occupe uniquement du contenu. Pour la forme, elle est gérée à part, avec des fichiers de configuration spécifiques au format HTML, LateX pour une sortie PDF ou un fichier de styles Word. Vous pouvez notamment créer vos propres templates d’entreprise ou d’organisation pour tous les documents internes ou à diffuser, une bonne fois pour toutes ! Le fichier _output.yml permet donc d’ajouter les éléments de forme à nos pages, notamment une feuille de style css, ou encore du texte et des liens avant ou après la liste des chapitres :
bookdown::gitbook:
  css: style.css
  config:
    toc:
      before: |
        <li><a href="./">A Minimal Book Example</a></li>
      after: |
        <li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>

Attention : Tous les fichiers doivent être encodés en UTF-8

Ok, et maintenant, on regarde à quoi il ressemble ce book ? Comme lorsqu’on développe un package R, on retrouve l’onglet Build, et il suffit de cliquer sur le bouton Build Book :

Et voilà, notre premier livre est créé !

Vous avez aussi la possibilité de créer votre {bookdown} en ligne de commande depuis R:

bookdown::render_book(
  input = "index.Rmd", 
  output_format = "bookdown::gitbook",
  output_dir = "docs")

Les bonus de {bookdown} par rapport à {rmarkdown}

Le package {bookdown} comble les manques de syntaxe de {rmarkdown} pour la rédaction de documents :

  • Créer des légendes pour vos graphiques et tables avec un formattage markdown. Dans le chunk qui crée votre table ou image, vous pouvez utiliser le paramètre fig.cap pour ajouter une légende. Lorsqu’on a de longues légendes de tables ou de graphes, ou lorsqu’on souhaite formatter le texte (e.g. texte en italique ou url), il est possible de rédiger en dehors du chunk avec la syntaxe markdown. Par exemple :
_Notez qu'il est nécessaire d'avoir une ligne vide au-dessus et en-dessous de la ligne où l'on écrit la légende._
(ref:maref) Un *scatterplot* des données `cars`
```{r foo, fig.cap='(ref:maref)'}
plot(cars)
```

Notez qu’il est nécessaire d’avoir une ligne vide au-dessus et en-dessous de la ligne où l’on écrit la légende.

  • Faire référence à des chapitres, des figures et des tableaux dans le texte du document. Utiliser la notation {#titre} pour nommer la référence à un titre du document. Utiliser \@ref(titre) pour y faire référence dans le texte. Fonctionnez de la même manière pour faire référence à une figure en ajoutant le prefixe de label fig comme ci-dessous avec \@ref(fig:pression) :
## Titre précédent {#avant}
Du texte.
## Réferences 
Faites référence à la figure \@ref(fig:pression). 
Mais aussi au chapitre précédent (chapitre \@ref(avant)).
(ref:pressioncap) La légende du graphique.
```{r pression, fig.cap='(ref:pressioncap)'}
plot(pressure)
```

  • numéroter et référencer les équations :
<!--numéroter--> 
\begin{equation} 
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:binom)
\end{equation} 
<!--référencer-->
\@ref(eq:binom)

Notez que {bookdown} comme {rmarkdown} permet d’écrire les équations au format LateX. L’équation ci-dessus apparaît donc comme sur l’équation (1)

  • écrire des théorèmes, lemmes, corrollaires, etc… qui sont numérotés :
```{theorem}
Ceci est mon théorème.
```

Ci-dessous, la liste des éléments que vous pouvez écrire et qui seront automatiquement numérotés en fonction du numéro de chapitre dans lequel on se trouve :

Par exemple, pour écrire une définition, on remplacera {theorem} par {definition} dans le code ci-dessus.

Il est aussi possible de nommer un théorème, notamment pour pouvoir y faire référence :

```{theorem, name = "Pythagore"}
Pour un triangle rectangle, si $C$ désigne la longuur de l'hypothénuse et 
$A$ et $B$  la longeur des deux autres cotés, alors on a : 
$$A^2 + B^2 = C^2$$
```

  • de la même manière, écrire des preuves, remarques ou solutions, qui sont elles non numérotées, en utilisant respectivement proof, remark, et solution. L’intérêt de ces classes particulières c’est qu’elles peuvent être customisée spécifiquement dans une feuille de style adaptée.
```{css}
.remark {
  color: red;
}
```
```{remark}
Voici notre remarque
```

Pour en savoir plus, n’hésitez pas à consulter la documentation du package : https://bookdown.org/yihui/bookdown/.

Pour créer des visuels de rapports sur mesure, adaptés au couleurs de votre entreprise ou de votre organisme, vous aurez besoin de vous familiariser avec le langage HTML, le CSS ou le LateX. Éventuellement, vous pouvez commencer par utiliser le package {pdfreport} pour vos rapports en PDF. Nous pouvons aussi vous accompagner pour la création de vos masques et templates pour vos rapports personnalisés avec R et {bookdown}.

 

À vos claviers ! Il est temps de rédiger cette documentation qui vous attend depuis si longtemps. Nous attendons vos exemples de {bookdown} et vos astuces pour leur rédaction.


À propos de l'auteur


Commentaires

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *


À lire également