2 Quarto et Rmarkdown

Note

A faire pour mi juin ça manque clairement de clarté:

Préciser les différences entre quarto render et quarto preview
Exécution de Python, Julia, Stata via Jupyter

2.1 Rappel sur la composition des documents

Un document de type html (format par défaut) est composé de deux parties¹.

Le corps du document: le body [ balise html ]. Trivialement obligatoire si on a quelque chose à écrire.
Les métadonnées: le header [balise html ]. Optionnel, mais comporte toute une série d’options allant du titre, date, activation d’une table des matières,…, aux options d’exécution des programmes ou de compilation du document. Il prend ici le nom de YAML. Ces métadonnées peuvent se trouver dans un fichier de configuration externe dont le type est .yml.

2.2 Principales différences

Indépendance par rapport à R

Quarto étant un logiciel, il est indépendant de R mais également de RStudio. Si le passage de Rmarkdown à Quarto se fait naturellement du côté de R, c’est le public Python qui est la principale cible de ce nouvel outil. En conséquences:
- Quarto peut pleinement s’utiliser avec d’autres interfaces comme VSCode ou Jupyterlab.
- Exécution directe des programmes via les noyaux Jupyter de Python, Julia mais aussi Stata².

Qualité des outputs

Amélioration des rendus des documents:
- Calage sur les normes html actuelles (html5).
- Documents en PDF de très grande qualité….. mais avec des durées de compilation particulièrement long.

Compilation multiformats

On peut simultanément produire un output en plusieurs formats (html, pdf, docx…) tout en gérant leur spécificité code source spécifique avec contenu dit conditionnel: éléments pour un contenu dynamique (html), élements pour un contenu statique (pdf, docs).

Vocabulaire des éléments de configuration/métadonnées (yaml)

Même si pour la configuration d’un document ou d’un projet des options supplémentaires ont été ajoutées afin d’améliorer la mise en page des documents, la gestion des blocs de codes ou la gestion de la compilation, les différences ne sont pas si nombreuses que cela par rapport à la dernière version de Rmarkdown.

C’est surtout dans certains éléments de vocabulaire que certaines modifications seront les plus visibles lors de la transformation d’un document ou d’un projet Rmarkdown existant en Quarto.

Deux exemples:

Pour indiquer le format du document, l’option output: est remplacée par l’option format:.
Le fichier de configuration d’un projet s’appelle maintenant _quarto.yml au lieu de _site.yml.

La durée de compilation en html et fichiers des outputs

La durée de compilation d’un fichier .qmd est plus longue que pour Rmarkdown. Quarto embarque plus de fonctionnalités ce qui se traduit par un poids des documents bien plus élevé.

A ce stade une grosse différence apparaît. Un output html Rmarkdown ne comporte qu’un seul fichier (nom-fichier.html) alors que pour Quarto un répertoire supplémentaire, appelé nom-fichier_libs est généré. Celui ci comporte tous les éléments de mise en forme du document sous forme de fichiers css, js… Lors d’une transmission par mail, ce repértoire devra également être ajouté, à moins d’indiquer dans une option que l’on souhaite générer un fichier html unique pour l’output. Ceci est réalisé dans la configuration du document avec une option spécifique: self-contained: true ou embed-resources:true³.

Rmarkdown: un seul fichier html généré

---
title: "XXXXX"
output: html
---

Quarto: un seul fichier html généré

---
title: "XXXXX"
format: html
embed-resources: true
---

Important

Ssur le serveux margaux à l’Ined… ça speed:

Ce problème de durée de compilation des document est levé si on utilise la version serveur (margaux) de RStudio…. mais on peut rencontrer des problèmes de chargement de certaines librairies R.
C’est le cas du package questionr (idem rmarkdown) et potentiellement d’autres package chargeant une appli Shiny. Normalement la mise à jour du package Shiny permet de résoudre le problème

2.3 Passer de Rmarkdown à Quarto

2.3.1 Compilation des fichiers

Rstudio: le bouton Render remplace le bouton Knitr, ce dernier étant réservé nativement à l’exécution de scripts R. Pour les autres moteurs de calcul (Python, Julia, Stata) c’est le notebook Jupyter qui exécute les scripts de programmation.
R: un package quarto permet comme Rmarkdown de compiler les fichiers via la console. Il me semble plutôt accessoire.
Quarto pousse à travailler en mode projet et à utiliser le terminal⁴. A l’aide de commandes relativement simples, on peut gèrer la compilation des documents:
- quarto render compile l’ensemble des fichiers .qmd d’un projet (par défaut en html)
  - Donc éviter de l’utiliser si on a modifié seulement un fichier d’un site ou d’un book.
  - Lorsque le fichier de configuration _quarto.yml a été modifié, il faut absolument l’utiliser pour que les modifications s’appliquent à tous les fichiers du projets (pages d’un site, chapitres d’un book).
- quarto render --to pdf compile l’ensemble des fichiers .qmd en pdf.
- Hors projet, il est possible de compiler un fichier dans le terminal en indiquant l’emplacement du fichier absolute_path/quarto render nom.qmd.

Quarto render versus quarto preview

Dans les faits, lorsqu’on compile avec le bouton RENDER, c’est la commande quarto preview qui est exécutée.
Quarto preview permet d’afficher l’aperçu de la page compilée dans la fenêtre Viewer ou la présentation dans la fenêtre Presentation. Quarto monte alors un serveur local (localhost:XXXX) dans un répertoire temporaire de la machine que l’on peut ouvrir en cliquant sur “Show in a new window”.
Si dans le terminal on compile via ma commande quarto preview, le rendu sera directement ouvert et mis à jour après avoir sauvegardé le fichier .qmd (raccourci clavier CTRL+S).
Attention l’affichage et la mise à jour du rendu via quarto preview me semble particulièrement lente. Sur un deuxième écran, j’ai plutôt tendance à ouvrir et mettre à jour directement le fichier html (j’ai 5 à 10 secondes de différences). Plus embêtant encore lorsqu’on navigue sur un site, le quarto preview est exécuté systématiquement lorsqu’on navigue d’une page à une autre.

2.3.2 Convertir un fichier .rmd en .qmd

Pour un document très simple, on peut convertir un fichier .rmd en .qmd par un simple changement du type de fichier.

Si on prend ce même document, sans l’option output et sans le script r setup, et qu’on l’enregistre en Quarto (.qmd):

2.4 Doit-on définitivement abandonner Rmarkdown ????

Quarto offre de nouvelles possibilités certes mais il n’est pas encore 100% stable⁵. Si on est moins regardant sur les questions de forme et d’esthétique des outputs, si l’utilisation de Rmarkdown s’arrête à la production de notebook simples en format html, le package reste une excellente solution, en particulier sous sa dernière version. La compilation est plus rapide et les documents pèsent bien moins lourd.

Mode visual, options des blocs de codes directement dans le corp du programme, nouveaux balisages pour <div> ou <span> … sont également intégrés dans les dernières versions de Rmarkdown.

C’est la même structuration en Latex↩︎
Avec le noyau Jupyter [nbstata]↩︎
Quarto conseille d’utiliser cette dernière qui s’applique totalement tant aux articles/notebook html qu’aux présentations revealjs ↩︎
Attention ctrl+v ne fonctionne pas. Soit click droit + coller ou ctrl+shift+v↩︎
Février 2024: mais cela s’améliore de version en version↩︎

--- fig-cap-location: top --- # Quarto et Rmarkdown ::: callout-note A faire pour mi juin ça manque clairement de clarté: * Préciser les différences entre `quarto render` et `quarto preview` * Exécution de Python, Julia, Stata via Jupyter ::: ## Rappel sur la composition des documents Un document de type html (format par défaut) est composé de deux parties^[C'est la même structuration en Latex]. * Le **corps du document**: le **body** [ balise html <body>]. Trivialement obligatoire si on a quelque chose à écrire. * Les **métadonnées**: le **header** [balise html <head>]. Optionnel, mais comporte toute une série d'options allant du titre, date, activation d'une table des matières,..., aux options d'exécution des programmes ou de compilation du document. Il prend ici le nom de **YAML**. Ces métadonnées peuvent se trouver dans un fichier de configuration externe dont le type est **`.yml`**. ## Principales différences **Indépendance par rapport à R** * Quarto étant un logiciel, il est indépendant de R mais également de RStudio. Si le passage de Rmarkdown à Quarto se fait naturellement du côté de R, c'est le public Python qui est la principale cible de ce nouvel outil. En conséquences: * Quarto peut pleinement s'utiliser avec d'autres interfaces comme **VSCode** ou **Jupyterlab**. * Exécution directe des programmes via les noyaux Jupyter de Python, Julia mais aussi Stata^[Avec le noyau Jupyter [[**nbstata**]](https://github.com/hugetim/nbstata)]. **Qualité des outputs** * Amélioration des rendus des documents: - Calage sur les normes html actuelles (html5). - Documents en PDF de très grande qualité..... mais avec des durées de compilation particulièrement long. **Compilation multiformats** On peut simultanément produire un output en plusieurs formats (html, pdf, docx...) tout en gérant leur spécificité code source spécifique avec contenu dit **conditionnel**: éléments pour un contenu dynamique (html), élements pour un contenu statique (pdf, docs). **Vocabulaire des éléments de configuration/métadonnées (yaml)** Même si pour la configuration d'un document ou d'un projet des options supplémentaires ont été ajoutées afin d'améliorer la mise en page des documents, la gestion des blocs de codes ou la gestion de la compilation, les différences ne sont pas si nombreuses que cela par rapport à la dernière version de Rmarkdown. C'est surtout dans certains éléments de vocabulaire que certaines modifications seront les plus visibles lors de la transformation d'un document ou d'un projet Rmarkdown existant en Quarto. Deux exemples: * Pour indiquer le format du document, l'option **`output:`** est remplacée par l'option **`format:`**. * Le fichier de configuration d'un projet s'appelle maintenant **`_quarto.yml`** au lieu de **`_site.yml`**. **La durée de compilation en html et fichiers des outputs** La durée de compilation d'un fichier .qmd est plus longue que pour Rmarkdown. Quarto embarque plus de fonctionnalités ce qui se traduit par un poids des documents bien plus élevé. A ce stade une grosse différence apparaît. Un output html Rmarkdown ne comporte qu'un seul fichier (**`nom-fichier.html`**) alors que pour Quarto un répertoire supplémentaire, appelé **nom-fichier_libs** est généré. Celui ci comporte tous les éléments de mise en forme du document sous forme de fichiers **css**, **js**... Lors d'une transmission par mail, ce repértoire devra également être ajouté, à moins d'indiquer dans une option que l'on souhaite générer un fichier html unique pour l'output. Ceci est réalisé dans la configuration du document avec une option spécifique: `self-contained: true` ou `embed-resources:true`^[Quarto conseille d'utiliser cette dernière qui s'applique totalement tant aux articles/notebook html qu'aux présentations revealjs ]. ```{.mf filename="Rmarkdown: un seul fichier html généré"} --- title: "XXXXX" output: html --- ``` ```{.mf filename="Quarto: un seul fichier html généré"} --- title: "XXXXX" format: html embed-resources: true --- ``` ::: {.callout-important} **Ssur le serveux margaux à l'Ined... ça speed**: Ce problème de durée de compilation des document est levé si on utilise la version serveur (margaux) de RStudio.... mais on peut rencontrer des problèmes de chargement de certaines librairies R. C'est le cas du package `questionr` (idem rmarkdown) et potentiellement d'autres package chargeant une appli Shiny. Normalement la mise à jour du package Shiny permet de résoudre le problème ::: ## Passer de Rmarkdown à Quarto ### Compilation des fichiers * Rstudio: le bouton **Render** remplace le bouton **Knitr**, ce dernier étant réservé nativement à l'exécution de scripts R. Pour les autres moteurs de calcul (Python, Julia, Stata) c'est le notebook Jupyter qui exécute les scripts de programmation. * R: un package `quarto` permet comme Rmarkdown de compiler les fichiers via la console. Il me semble plutôt accessoire. * Quarto pousse à travailler en mode projet et à utiliser le terminal^[Attention `ctrl+v` ne fonctionne pas. Soit click droit + coller ou `ctrl+shift+v`]. A l'aide de commandes relativement simples, on peut gèrer la compilation des documents: * `quarto render` compile l'ensemble des fichiers .qmd d'un projet (par défaut en html) * Donc éviter de l'utiliser si on a modifié seulement un fichier d'un site ou d'un book. * Lorsque le fichier de configuration _quarto.yml a été modifié, il faut absolument l'utiliser pour que les modifications s'appliquent à tous les fichiers du projets (pages d'un site, chapitres d'un book). * `quarto render --to pdf` compile l'ensemble des fichiers .qmd en pdf. * Hors projet, il est possible de compiler un fichier dans le terminal en indiquant l'emplacement du fichier `absolute_path/quarto render nom.qmd`. **Quarto render versus quarto preview** * Dans les faits, lorsqu'on compile avec le bouton RENDER, c'est la commande `quarto preview` qui est exécutée. * Quarto preview permet d'afficher l'aperçu de la page compilée dans la fenêtre Viewer ou la présentation dans la fenêtre Presentation. Quarto monte alors un serveur local (localhost:XXXX) dans un répertoire temporaire de la machine que l'on peut ouvrir en cliquant sur "*Show in a new window*". * Si dans le terminal on compile via ma commande `quarto preview`, le rendu sera directement ouvert et mis à jour après avoir sauvegardé le fichier .qmd (raccourci clavier **CTRL+S**). * Attention l'affichage et la mise à jour du rendu via `quarto preview` me semble particulièrement lente. Sur un deuxième écran, j'ai plutôt tendance à ouvrir et mettre à jour directement le fichier html (j'ai 5 à 10 secondes de différences). Plus embêtant encore lorsqu'on navigue sur un site, le quarto preview est exécuté systématiquement lorsqu'on navigue d'une page à une autre. ### Convertir un fichier .rmd en .qmd Pour un document très simple, on peut convertir un fichier `.rmd` en `.qmd` par un simple changement du type de fichier. ::: {.columns} ::: {.column width="42.5%"} ![Document rmd sans l'option output](img1/img1.png){group=g1} ::: ::: {.column width="5%"} ::: ::: {.column width="42.5%"} ::: {.box_img} ![Rendu html](img1/img2.png) ::: ::: ::: Si on prend ce même document, sans l'option `output` et sans le script `r setup`, et qu'on l'enregistre en Quarto (.qmd): ::: {.columns} ::: {.column width="42.5%"} ![Document qmd sans l'option output](img1/img3.png){group=g1} ::: ::: {.column width="5%"} ::: ::: {.column width="42.5%"} ::: {.box_img} ![Rendu html](img1/img4.png){group=g1} ::: ::: ::: ## Doit-on définitivement abandonner Rmarkdown ???? Quarto offre de nouvelles possibilités certes mais il n'est pas encore 100% stable^[Février 2024: mais cela s'améliore de version en version]. Si on est moins regardant sur les questions de forme et d'esthétique des outputs, si l'utilisation de Rmarkdown s'arrête à la production de notebook simples en format html, le package reste une excellente solution, en particulier sous sa dernière version. La compilation est plus rapide et les documents pèsent bien moins lourd. Mode visual, options des blocs de codes directement dans le corp du programme, nouveaux balisages pour `<div>` ou `<span>` ... sont également intégrés dans les dernières versions de Rmarkdown.