Rendu

Introduction

Ce guide fournit une vue d’ensemble de la façon d’optimiser les processus de rendu de vos documents en utilisant Quarto. Que vous travailliez avec des notebooks Jupyter ou des fichiers markdown Quarto, ce tutoriel améliorera votre productivité en vous apprenant ce qui suit:

  • Prévisualisation des documents : Prévisualisez rapidement votre travail dans différents formats directement depuis le terminal.
  • Rendu complet : Comprendre les différentes commandes de rendu pour générer des sorties HTML, PDF ou Docx.
  • Paramétrage : Personnalisez les documents de manière dynamique en configurant et en utilisant des paramètres dans les environnements Python et R.
  • Stratégies de mise en cache : Mettre en œuvre la mise en cache pour accélérer le processus de rendu et éviter les calculs redondants.
  • Contrôles d’exécution : Utilisez les options d’exécution flexibles de Quarto pour gérer comment et quand votre code s’exécute.


Prévisualisation

Prévisualisation d’un document:

Terminal
# prévisualisation en html
quarto preview document.qmd

# prévisualisation en pdf
quarto preview document.qmd --to pdf

# Prévisualiser un Notebook Jupyter
quarto preview document.ipynb

Rendu

Rendre les documents dans différents formats en utilisant des commandes comme:

Terminal
# tous les formats spécifiés, le format par défaut est html
quarto render document.qmd

# Rendu en pdf ou docx
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

Pour les notebooks Jupyter (.ipynb), utilisez: quarto render document.ipynb

Note

Note : Pour les fichiers .ipynb, utilisez --execute pour exécuter les cellules pendant le rendu (si vous ne les avez pas déjà exécutées dans le notebook).

Terminal
quarto render notebook.ipynb --execute

Vous pouvez également spécifier ce comportement dans la page d’accueil YAML du Notebooks:

---
title: "Mes Notebooks"
execute: 
  enabled: true
---

Paramétrage

Configurer les paramètres pour créer différentes variantes d’un document en utilisant Jupyter ou Knitr:

  • Dans Jupyter, Quarto adopte la syntaxe Papermill pour les paramètres.
  • Marquer une cellule avec parameters et configurer des valeurs par défaut pour paramétrer un document.
```{python}
#| tags: [parameters]

alpha = 0.1
ratio = 0.1
```

Les paramètres sont disponibles dans l’environnement de haut niveau:

```{python}
alpha
```

Utiliser l’option YAML params pour définir les paramètres:

---
params:
  alpha: 0.1
  ratio: 0.1
---

Les paramètres sont disponibles dans la liste params:

```{r}
params$alpha
```

Effectuer le rendu avec différents paramètres en utilisant -P for both .ipynb and .qmd:

quarto render document.ipynb -P alpha:0.2 -P ratio:0.3

Ou utiliser un fichier YAML pour les paramètres et --execute-params:

quarto render document.qmd --execute-params params.yml

Mise en cache

Mettre en cache l’exécution du code pour accélérer le rendu et éviter de réexécuter du code inchangé.

Configurer

Le paramétrage dépend du moteur d’exécution que vous utilisez (Jupyter ou Knitr).

Installer Jupyter Cache:

  • Mac/Linux python3 -m pip install jupyter-cache
  • Windows py -m pip install jupyter-cache

Activer la mise en cache globalement dans YAML:

---
title: "Mon document"
format: html
execute: 
  cache: true
---

Ou au niveau du projet:

project:
  type: website
  
format:
  html:
    theme: united
    
execute:
  cache: true
Note

Si vous le souhaitez, vous pouvez utiliser la ligne de commande jcache pour gérer les caches des Notebooks. Voir la documentation Jupyter Cache.

Activer la mise en cache globalement dans YAML:

---
title: "Mon document"
format: html
execute: 
  cache: true
---

Ou individuellement par cellule:

```{r}
#| cache: true

summary(cars)
```

En savoir plus:

Rendu

Vous pouvez utiliser les options de ligne de commande quarto render pour contrôler le comportement de la mise en cache sans changer le code du document.

Contrôler la mise en cache de quarto render avec les options de la ligne de commande:

  • --cache: Forcer la mise en cache de tous les blocs (même si elle n’est pas activée dans les options).
  • --no-cache: Désactiver la mise en cache pour tous les blocs (même si elle est activée dans les options).
  • --cache-refresh: Rafraîchir le cache pour tous les morceaux (même s’il n’a pas été invalidé).

Alternatives

Désactiver l’exécution

Pour le travail en prose/markdown, désactivez l’exécution du code avec:

execute: 
  enabled: false

Dans les notebooks Jupyter .ipynb, le code ne s’exécute pas avec quarto render par défaut.

Geler l’exécution

L’option freeze empêche le re-rendu des documents lors d’un rendu complet du projet ou autorise le re-rendu uniquement lorsque leur source change.

# Ne jamais refaire le rendu pendant le rendu du projet
execute:
  freeze: true  
# Rendu uniquement lorsque la source change
execute:
  freeze: auto

Freeze affecte l’exécution pendant les rendus complets du projet. Pour les documents individuels ou les rendus de sous-répertoires, l’exécution du code est toujours effectuée.

Terminal
# Rendu d'un seul document (exécute toujours le code)
quarto render document.qmd

# Render project subdirectory (toujours exécuter le code)
quarto render articles

Références