1 Installation Quarto et gestion des fichiers

1.1 Installation et mise à jour de Quarto

Depuis juillet 2022, Quarto est installé automatiquement à RStudio.
Les mises à jour de Quarto se font directement sur le site officiel.

Après cela aucune opération d’installation ou de désinstallation n’est nécessaire: ce n’est pas un package, mais un logiciel à part entière exécutable dans une interface.

Depuis le site officiel, il est possible de:
- Installer la version courante de Quarto si la version de Rstudio n’a pas été encore mise à jour.
- Réinstaller une version antérieure si la version courante à été désinstaller.
- Installer une pre-release. Cela n’est pas conseillé.

La désinstallation de quarto est effectuée via une application: outil d’installation/désinstallation de l’OS, ccleaner…

1.2 Autres installations

1.2.1 Le package R de quarto

Le package R Quarto¹ permet de faire quelques opérations à partir de la console R: vérification de la version de Quarto installée, compilation d’un document… Quarto étant un logiciel, son installation est plutôt accessoire.

install.packages("quarto")
library(quarto)

Verifier la version de Quarto

library(quarto)
quarto_version()

[1] '1.5.41'

Compiler un fichier Quarto à partir de la console

quarto::quarto_render("filename.qmd")

1.2.2 Tinytex

Pour les sorties en format PDF, dont les présentations en format beamer, installer un compilateur Latex comme tinytex (recommandé).

Méthode 1

Installation du package via la console R

Installation R console

install.packages("tinytex")

Méthode 2

Dans le terminal (recommandé):

Installation recommandée: terminal

# Click droit pour coller dans le terminal ou ctrl+shift+V
quarto install tinytex

Pour vérifier la version de tinytex, dans le terminal: quarto list tools
Pour en savoir plus sur les moteurs PDF: [documentation Quarto]

On peut également checker toutes linstallations utilisées par Quarto avec quarto check

Installations au 06-06-2024

quarto check

[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.2.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.41.0: OK
      Typst version 0.11.0: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.5.41
      Path: C:\Users\thevenin_m\AppData\Local\Programs\Quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: v2024.06
      Chromium: 869685

[>] Checking LaTeX....................OK
      Using: TinyTex
      Path: C:\Users\thevenin_m\AppData\Roaming\TinyTeX\bin\windows\
      Version: 2024

[>] Checking basic markdown render....OK

[>] Checking Python 3 installation....OK
      Version: 3.12.3
      Path: C:/Users/thevenin_m/AppData/Local/Programs/Python/Python312/python.exe
      Jupyter: 5.7.2
      Kernels: ir, nbstata, python3

[>] Checking Jupyter engine render....OK

[>] Checking R installation...........OK
      Version: 4.4.0
      Path: C:/Users/thevenin_m/AppData/Local/Programs/R/R-4.4.0
      LibPaths:
        - C:/Users/thevenin_m/AppData/Local/Programs/R/R-4.4.0/library
      knitr: 1.47
      rmarkdown: 2.27

[>] Checking Knitr engine render......OK

1.3 Création d’un fichier `qmd`

Lorsque Quarto est installé, le menu file de RStudio ajoute deux options supplémentaires au sous menu new file: Quarto document, Quarto presentation.

Quarto document:
- Notebook, article .
- Documents intéractifs:
  - Shiny .
  - Observable .
  - A partir de la version 1.4, un Dashboard .
Quarto presentation:
- Revealjs (javascript): .
- Beamer (Latex): .
- Powerpoint (windows ou libre office) .
A l’ouverture:
- un fichier .qmd minimal avec quelques éléments de texte formatés en markdown ainsi qu’un bloc de codes exécutable est créé. Selon les options renseignées dans la fenêtre de création, il comporte un Header (yaml) avec par exemple un titre, un nom, un format.

1.4 Création d’un projet

Projets website, book, blog:
Pour les documents avec des structures enrichies, la création se fait via un projet: new project=> new directory: Quarto website, Quarto book, Quarto blog et depuis janvier 2024 (v1.4) un projet Quarto manuscript.

Quarto website
Quarto book
Quarto blog
Quarto manuscript
A l’ouverture:
- Un ou plusieurs fichiers .qmd. Pour les blogs, dont le contenu est organisé sous forme d’articles, des sous répertoires avec deux exemples d’articles (.qmd).
- Un fichier de configuration _quarto.yml minimal propre au contenu.
- Un fichier .Rproj.

Privilégier l’ouverture du fichier .Rproj

Pour travailler sur les fichiers associés à un projet, pensez à toujours ouvrir le fichier nom_projet.Rproj et non des fichiers individuels:

Dans le terminal le dossier racine se positionnera sur celui du projet.
Dans la fenêtre files de RStudio, on peut accédere directements à l’ensemble des fichiers du projet.

Privilégier le terminal pour créer un projet quarto

1.4.0.1 Via la création d’un projet Quarto

La création peut d’un projet avec un squelette peut se faire directement via le terminal de RStudio avec une simple ligne de commande après s’être positionné sur un répertoire racine. Je dis cela car l’ouverture de la fenêtre de création d’un projet R peut prendre pas mal de seconde, chez moi c’est plutôt 30 secondes.

Dans le terminal:

quarto create project website
quarto create project book
quarto create project blog

On vous demandera ensuite de choisir un nom pour le répertoire et de choisir l’IDE (Rstudio ou Vscode).

En animation:

1.4.0.2 Via la création d’un projet R

Dans la console R on peut générer un projet R avec la fonction create_project() du package usethis
Dans le terminal de RStudio, on pourra créer directement les fichiers ou les répertoires qui seront utiles avec la commande touch

Etapes de l’animation qui suit:

On génère le répertoire du projet dans le terminal: mkdir mon_book².
On charge le pakqge usethis dans la console R: library(usethis)
On génère le projet avec la fonction create_project() en renseignant le chemin du répertoire mon_book: create_project("c:/users/thevenin_m/desktop/quarto/mon_book/")
Rstudio va réouvrir une session en se positionnant dans le répertoire du projet. La fonction génère automatiquement un sous répertoire R, on peut le supprimer si on estime ne pas en avoir besoin: dans le terminal rm -r R³
On peut créer directement des fichiers vides avec la commande touch:
- touch _quarto.yml [configuration du book]
- touch index.qmd [page d’accueil du book, toujours conserver le nom index]
- touch chapitre1.qmd
- touch chapitre2.qmd

Remarques

Multicontenu:

A l’absolu, une même documentation peut simultanément comporter tous ces types de contenu. Ce support est à la fois un book avec un chapitrage dans la barre verticale à gauche (sidebar) et un website avec des éléments de navigation dans une barre horizontale en haut (navbar). Et on pourrait sans problème y ajouter un contenu blog dans la page d’accueil si le type de projet avaient été un website plutôt qu’un book.

Déploiement sur une plateforme git [Se reporter à la partie 2]:

Si on souhaite déployer sa documentation sur une forge git comme gitlab ou github, ont doit créer un projet pour effectuer les opérations de synchronisation en le repertoire de travail en local et le répertoire distant (remote).

New project => Version control => Git
- On peut produire dans un premier temps sa documentation dans un projet , puis reverser les fichiers sources dans un projet git. Pour Github seulement, avec les fonction use_git(project_path) et use_github() du package usethis on pourra générer ce répertoire distant directement à partir de RStudio.
- Approche classique: après avoir créer le dépôt distant sur une plateforme git, on le clone sur le local. On génère ensuite son projet de documentation.

Nécessite une version Rtools relativement à jour: min v4↩︎
c’est un sous répertoire du répertoire quarto qui se trouve sur le bureau, le terminal est positionné sur ce répertoire↩︎
rm pour remove, -r pour indiquer qu’on supprime un répertoire et R pour le nom du répertoire↩︎

# Installation Quarto et gestion des fichiers ## Installation et mise à jour de Quarto * Depuis juillet 2022, Quarto est installé automatiquement à RStudio. * Les mises à jour de Quarto se font directement sur le [site officiel](https://quarto.org/docs/get-started/). Après cela aucune opération d'installation ou de désinstallation n'est nécessaire: ce n'est pas un package, mais un logiciel à part entière exécutable dans une interface. * Depuis le site officiel, il est possible de: - Installer la version courante de Quarto si la version de Rstudio n'a pas été encore mise à jour. - Réinstaller une version antérieure si la version courante à été désinstaller. - Installer une pre-release. Cela n'est pas conseillé. ::: {.center} ::: {layout="[15,-2,15]" layout-valign="bottom"} ::: {.box_img} ![<https://quarto.org/docs/get-started/>](img1/c12.png){group="g1"} ::: ::: {.box_img} ![<https://quarto.org/docs/download/>](img1/c13.png){group="g1"} ::: ::: ::: * La désinstallation de quarto est effectuée via une application: outil d'installation/désinstallation de l'OS, **ccleaner**... ## Autres installations ### Le package R de quarto * Le package R Quarto^[Nécessite une version `Rtools` relativement à jour: min v4] permet de faire quelques opérations à partir de la console R: vérification de la version de Quarto installée, compilation d'un document... Quarto étant un logiciel, son installation est plutôt accessoire. ```{.mf} install.packages("quarto") library(quarto) ``` ```{r filename="Verifier la version de Quarto"} #| warning: false library(quarto) quarto_version() ``` ```{.md filename="Compiler un fichier Quarto à partir de la console"} quarto::quarto_render("filename.qmd") ``` ### Tinytex Pour les sorties en format PDF, dont les présentations en format **beamer**, installer un compilateur Latex comme **`tinytex`** (recommandé). **Méthode 1** * Installation du package via la console R ```{r filename="Installation R console"} #| echo: true #| eval: false install.packages("tinytex") ``` **Méthode 2** Dans le terminal (recommandé): ```{r filename="Installation recommandée: terminal"} #| echo: true #| eval: false # Click droit pour coller dans le terminal ou ctrl+shift+V quarto install tinytex ``` * Pour vérifier la version de tinytex, dans le terminal: `quarto list tools` * Pour en savoir plus sur les moteurs PDF: [[documentation Quarto]](https://quarto.org/docs/output-formats/pdf-engine.html) On peut également checker toutes linstallations utilisées par Quarto avec `quarto check` ::: {.callout-note collapse=TRUE} ### Installations au 06-06-2024 <br> ```{.bash} quarto check ``` ```{.bash} [>] Checking versions of quarto binary dependencies... Pandoc version 3.2.0: OK Dart Sass version 1.70.0: OK Deno version 1.41.0: OK Typst version 0.11.0: OK [>] Checking versions of quarto dependencies......OK [>] Checking Quarto installation......OK Version: 1.5.41 Path: C:\Users\thevenin_m\AppData\Local\Programs\Quarto\bin CodePage: 1252 [>] Checking tools....................OK TinyTeX: v2024.06 Chromium: 869685 [>] Checking LaTeX....................OK Using: TinyTex Path: C:\Users\thevenin_m\AppData\Roaming\TinyTeX\bin\windows\ Version: 2024 [>] Checking basic markdown render....OK [>] Checking Python 3 installation....OK Version: 3.12.3 Path: C:/Users/thevenin_m/AppData/Local/Programs/Python/Python312/python.exe Jupyter: 5.7.2 Kernels: ir, nbstata, python3 [>] Checking Jupyter engine render....OK [>] Checking R installation...........OK Version: 4.4.0 Path: C:/Users/thevenin_m/AppData/Local/Programs/R/R-4.4.0 LibPaths: - C:/Users/thevenin_m/AppData/Local/Programs/R/R-4.4.0/library knitr: 1.47 rmarkdown: 2.27 [>] Checking Knitr engine render......OK ``` ::: ## Création d'un fichier `qmd` Lorsque Quarto est installé, le menu **file** de RStudio ajoute deux options supplémentaires au sous menu **new file**: ***Quarto document***, **Quarto presentation**. * **Quarto document**: * Notebook, article [{{< fa solid link size=footnotesize >}}](https://quarto-dev.github.io/quarto-gallery/page-layout/tufte.html). * Documents intéractifs: * Shiny [{{< fa solid link size=footnotesize >}}](https://quarto.org/docs/interactive/ojs/examples/penguins.html). * Observable [{{< fa solid link size=footnotesize >}}](https://jjallaire.shinyapps.io/diamonds-explorer/). * A partir de la version 1.4, un Dashboard [{{< fa solid link size=footnotesize >}}](https://quarto.org/docs/dashboards/). * **Quarto presentation**: * Revealjs (javascript): [{{< fa solid link size=footnotesize >}}](https://quarto.org/docs/presentations/revealjs/demo/#/title-slide). * Beamer (Latex): [{{< fa solid link size=footnotesize >}}](https://quarto-dev.github.io/quarto-gallery/presentations/beamer/beamer.pdf). * Powerpoint (windows ou libre office) [{{< fa solid link size=footnotesize >}}](https://github.com/quarto-dev/quarto-gallery/blob/main/presentations/powerpoint/powerpoint.pptx). * **A l'ouverture**: - un fichier .qmd minimal avec quelques éléments de texte formatés en markdown ainsi qu'un bloc de codes exécutable est créé. Selon les options renseignées dans la fenêtre de création, il comporte un *Header* (**yaml**) avec par exemple un titre, un nom, un format. ## Création d'un projet **Projets website, book, blog**: Pour les documents avec des structures enrichies, la création se fait via un projet: **new project=> new directory**: **Quarto website**, **Quarto book**, **Quarto blog** et depuis janvier 2024 (v1.4) un projet **Quarto manuscript**. ::: {.center} ::: {.box_img} ![](img1/c11.png){width=70%} ::: ::: * **Quarto website** [{{< fa solid link >}}](https://quarto.org/) * **Quarto book** [{{< fa solid link >}}](https://mthevenin.github.io/analyse_duree/) * **Quarto blog** [{{< fa solid link >}}](https://mthevenin.github.io/assistoolsms/) * **Quarto manuscript** [{{< fa solid link >}}](https://quarto-ext.github.io/manuscript-template-jupyter/) * **A l'ouverture**: - Un ou plusieurs fichiers `.qmd`. Pour les blogs, dont le contenu est organisé sous forme d'articles, des sous répertoires avec deux exemples d'articles (.qmd). - Un fichier de configuration `_quarto.yml` minimal propre au contenu. - Un fichier .Rproj. ::: callout-important ### Privilégier l'ouverture du fichier **.Rproj** Pour travailler sur les fichiers associés à un projet, pensez à toujours ouvrir le fichier **nom_projet.Rproj** et non des fichiers individuels: * Dans le terminal le dossier racine se positionnera sur celui du projet. * Dans la fenêtre **files** de RStudio, on peut accédere directements à l'ensemble des fichiers du projet. ::: ::: {.callout-tip collapse=true} ### Privilégier le terminal pour créer un projet quarto #### Via la création d'un projet Quarto La création peut d'un projet avec un squelette peut se faire directement via le terminal de RStudio avec une simple ligne de commande après s'être positionné sur un répertoire racine. Je dis cela car l'ouverture de la fenêtre de création d'un projet R peut prendre pas mal de seconde, chez moi c'est plutôt 30 secondes. Dans le terminal: * `quarto create project website` * `quarto create project book` * `quarto create project blog` On vous demandera ensuite de choisir un nom pour le répertoire et de choisir l'IDE (Rstudio ou Vscode). En animation: ::: {.center} ::: {.box_img} ![](img1/video1.gif) ::: ::: #### Via la création d'un projet R * Dans la console R on peut générer un projet R avec la fonction `create_project()` du package **`usethis`** * Dans le terminal de RStudio, on pourra créer directement les fichiers ou les répertoires qui seront utiles avec la commande `touch` Etapes de l'animation qui suit: * On génère le répertoire du projet dans le terminal: `mkdir mon_book`^[c'est un sous répertoire du répertoire quarto qui se trouve sur le bureau, le terminal est positionné sur ce répertoire]. * On charge le pakqge `usethis` dans la console R: `library(usethis)` * On génère le projet avec la fonction `create_project()` en renseignant le chemin du répertoire *mon_book*: `create_project("c:/users/thevenin_m/desktop/quarto/mon_book/")` * Rstudio va réouvrir une session en se positionnant dans le répertoire du projet. La fonction génère automatiquement un sous répertoire R, on peut le supprimer si on estime ne pas en avoir besoin: dans le terminal `rm -r R`^[rm pour remove, -r pour indiquer qu'on supprime un répertoire et R pour le nom du répertoire] * On peut créer directement des fichiers vides avec la commande `touch`: * `touch _quarto.yml` [configuration du book] * `touch index.qmd` [page d'accueil du book, toujours conserver le nom index] * `touch chapitre1.qmd` * `touch chapitre2.qmd` ::: {.center} ::: {.box_img} ![](img1/video2.gif) ::: ::: ::: **Remarques** ***Multicontenu***: A l'absolu, une même documentation peut simultanément comporter tous ces types de contenu. Ce support est à la fois un *book* avec un chapitrage dans la barre verticale à gauche (*sidebar*) et un *website* avec des éléments de navigation dans une barre horizontale en haut (*navbar*). Et on pourrait sans problème y ajouter un contenu blog dans la page d'accueil si le type de projet avaient été un *website* plutôt qu'un *book*. ***Déploiement sur une plateforme git [Se reporter à la partie 2]***: Si on souhaite déployer sa documentation sur une forge git comme gitlab ou github, ont doit créer un projet pour effectuer les opérations de synchronisation en le repertoire de travail en local et le répertoire distant (*remote)*. * **New project** => **Version control** => **Git** * On peut produire dans un premier temps sa documentation dans un projet , puis reverser les fichiers sources dans un projet git. Pour Github seulement, avec les fonction `use_git(project_path)` et `use_github()` du package **`usethis`** on pourra générer ce répertoire distant directement à partir de RStudio. * Approche classique: après avoir créer le dépôt distant sur une plateforme git, on le clone sur le local. On génère ensuite son projet de documentation.