Tableaux

Introduction

Ce guide donne des indications pour créer et styliser des tableaux dans les documents markdown Quarto et les notebooks Jupyter.

Les sujets abordés incluent:

  • Tableaux Markdown: Apprenez à créer des tableaux avec Markdown, en utilisant des outils comme TableauxGenerator pour plus de simplicité.
  • Styler les tableaux: Appliquer les classes Bootstrap pour améliorer l’apparence des tableaux avec des styles tels que .striped and .hover.
  • Ajustement des largeurs: Contrôlez la largeur des colonnes avec l’attribut tbl-colwidths, pour des tableaux individuels ou pour l’ensemble du document.
  • Référencement des tableaux: Les tableaux peuvent être référencés dans le texte, y compris les tableaux computationnels, en utilisant le préfixe tbl- dans les étiquettes.
  • Regroupement des sous-tableaux: Organisez les sous-tableaux apparentés dans une div pour une mise en page structurée.
  • Caption Placement: Choisissez l’emplacement des légendes en utilisant tbl-cap-location pour positionner les légendes de manière efficace.
  • Tableaux computationnels: Afficher des tableaux computationnels en utilisant le package Python tabulate ou la fonction R kable(), avec des options de mise en page et de sous-titres.
  • Tableaux en grille: Explorer les tableaux Markdown en grille avancés pour les cellules riches en contenu, avec des options d’alignement du contenu des cellules.

Ce contenu sert de ressource pratique pour améliorer la présentation et la fonctionnalité des tableaux dans la documentation technique.

Tableaux Markdown

Utiliser des outils en ligne tels que [TableauxGenerator] (https://tablesgenerator.com/markdown_tables) pour générer des tableaux en markdown.

Tableaux classiques

Le caractère : peut être utilisé pour spécifier l’alignement des colonnes.

  • --- pour l’alignement par défaut (D)
  • :---- pour l’alignement à gauche (L)
  • ----: pour un alignement à droite (R)
  • :---: pour centré (C)
| D       | L    | R     | C      |
|---------|:-----|------:|:------:|
| 12      | 12   |    12 |   12   |
| 123     | 123  |   123 |  123   |
| 1       | 1    |     1 |   1    |

: Démonstration de la syntaxe classique des tableaux
Démonstration de la syntaxe classique des tableaux
D L R C
12 12 12 12
123 123 123 123
1 1 1 1

Utiliser les classes Bootstrap

Liste des classes pouvant être utilisées dans les tableaux:

"primary", "secondary", "success", "danger", "warning", "info", "light", "dark", "striped", "hover", "active", "bordered", "borderless", "sm", "responsive", "responsive-sm", "responsive-md", "responsive-lg", "responsive-xl", "responsive-xxl".

Par exemple, utiliser {.striped .hover} dans votre Markdown créera un tableau avec des couleurs de lignes alternées et mettra en évidence les lignes lorsque vous les survolez:

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Tableau démo {.striped .hover}
Tableau démo
Col1 Col2 Col3
A B C
E F G
A G G

Largeur des colonnes

Utilisez l’attribut tbl-colwidths, qui peut être ajouté après la légende. Par exemple:

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Tableau de démo {tbl-colwidths="[75,25]"}
Tableau de démo
Col1 Col2 Col3
A B C
E F G
A G G
Note

Notez que si votre tableau n’a pas de légende, vous pouvez toujours spécifier uniquement des sous-identifiants tbl-colwidths

La largeur des colonnes peut également être spécifiée au niveau du document (par exemple, pour obtenir des largeurs uniformes dans un ensemble de tableaux):

---
title: "Mon document"
format: html
tbl-colwidths: [75,25]
---

Références croisées

Tableaux issus du code

  1. Inclure un préfixe tbl- dans le label pour le référencement
  2. Référencement des tableaux en utilisant le préfixe @:
```{python}
#| label: tbl-planets
#| tbl-cap: Objet astronomique

from IPython.display import Markdown
from tabulate import tabulate
table = [["A","B","C"],
         ["E","F","G"],
         ["A","G","G"]]
Markdown(tabulate(
  table, 
  headers=["Col1","Col2", "Col3"]
))
```
Table 1: Objet astronomique
Col1 Col2 Col3
A B C
E F G
A G G

Référencement du tableau:

voir @tbl-planets.

Sortie:

voir Table 1.

Tableaux Markdown

  1. Ajouter une légende sous le tableau
  2. Inclure une étiquette #tbl- entre accolades à la fin de la légende.

Exemple:

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Ma légende {#tbl-letters}

Voir @tbl-letters.

Sortie:

Table 2: Ma légende
Col1 Col2 Col3
A B C
E F G
A G G

Voir Table 2.

Utiliser la syntaxe div pour le référencement des tableaux:

::: {#tbl-letters}

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

Ma légende

:::

Sous-tableaux

  • Pour combiner des sous-tableaux en une seule composition, utilisez une div avec un identifiant principal.
  • Attribuez des sous-identifiants et des légendes facultatives à chaque tableau à l’intérieur de la div.
::: {#tbl-panel layout-ncol=2}
| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Premier tableau {#tbl-first}

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Deuxième tableau {#tbl-second}

Légende principale
:::

Voir @tbl-panel pour plus de détails, en particulier @tbl-second.

Sortie:

Deux tableaux côte à côte. Les deux tableaux comportent 3 colonnes et 4 lignes. Le tableau de gauche est intitulé '(a) Premier tableau'. Le tableau de droite est intitulé '(b) Second tableau'. Le texte 'Tableau 1 : Légende principale' est centré au-dessus des deux tableaux.

Note

Notez que la “légende principale” du tableau est fournie dans le dernier bloc de la div qui le contient.

Emplacement des légendes

  • L’emplacement par défaut est au-dessus du tableau.
  • Utiliser tbl-cap-location to change the location to top, bottom, or margin. Par exemple:
---
tbl-cap-location: top
---

Computationnels

En utilisant Python. Afficher un tableau markdown en utilisant le package Python tabulate avec la fonction Markdown() du module IPython display:

```{python}
#| label: tbl-planet-measures
#| tbl-cap: Objet astronomique

from IPython.display import Markdown
from tabulate import tabulate
table = [["A","B","C"],
         ["E","F","G"],
         ["A","G","G"]]
Markdown(tabulate(
  table, 
  headers=["Col1","Col2", "Col3"]
))
```
Table 3: Objet astronomique
Col1 Col2 Col3
A B C
E F G
A G G

En utilisant R:

  • Afficher un tableau markdown en utilisant la fonction knitr kable().
  • Appliquez l’option tbl-cap pour ajouter une légende et l’option tbl-colwidths pour spécifier la largeur des colonnes.
```{r}
#| label: tbl-cars
#| tbl-cap: "Voitures"
#| tbl-colwidths: [60,40]

kable(head(cars))
```

Si votre cellule de code produit plusieurs tableaux, vous pouvez également spécifier les sous-capitaux et la mise en page en utilisant les options de la cellule:

```{python}
#| label: tbl-example
#| tbl-cap: "Exemple"
#| tbl-subcap: 
#|   - "MPG"
#|   - "Taxis"
#| layout-ncol: 2

import seaborn as sns
from IPython.display import Markdown, display
mpg = sns.load_dataset("mpg").head(10)
taxis = sns.load_dataset("taxis").head(10)

display(Markdown(mpg.to_markdown(index = False)))
display(Markdown(taxis.to_markdown(index = False)))
```

Notez que nous utilisons la fonction display() importée de IPython afin de pouvoir afficher plusieurs résultats à partir d’une seule cellule (par défaut, les cellules n’affichent que leur dernière expression).

```{r}
#| label: tbl-example
#| tbl-cap: "Exemple"
#| tbl-subcap: 
#|   - "Voitures"
#|   - "Pression"
#| layout-ncol: 2

library(knitr)
kable(head(cars))
kable(head(pressure))
```

Tableaux en grille

Les tableaux en grille sont un type plus avancé de tableaux Markdown qui permettent de créer des blocs arbitraires (paragraphes multiples, blocs de code, listes, etc.). Par exemple:

+-----------+-----------+--------------------+
| Col1      | Col2      | Col3               |
+===========+===========+====================+
| A         | B         | - C1               |
|           |           | - C2               |
+-----------+-----------+--------------------+
| E         | F         | - G1               |
|           |           | - G2               |
+-----------+-----------+--------------------+

: Exemple de tableau en grille.

Ce qui ressemble à ceci lorsqu’il est rendu en HTML:

Exemple de tableau en grille.
Col1 Col2 Col3
A B
  • C1
  • C2
E F
  • G1
  • G2

La ligne = sépare l’en-tête du corps du tableau et peut être omise pour un tableau sans en-tête. Les cellules qui s’étendent sur plusieurs colonnes ou lignes ne sont pas prises en charge.

Les alignements peuvent être spécifiés comme pour les tableaux classiques, en plaçant des deux points aux limites de la ligne de séparation après l’en-tête:

  • ===: pour un alignement à droite (R)
  • :=== pour l’alignement à gauche (L)
  • :===: pour centré (C)
+---------+--------+------------------+
| R       | L      | C                |
+========:+:=======+:================:+
| A       | B      | C                |
+---------+--------+------------------+

Ce qui ressemble à ceci lorsqu’il est rendu en HTML:

R L C
A B C

Pour les tableaux sans en-tête, les deux-points sont placés sur la ligne supérieure:

+----------:+:----------+:--------:+
| A         | B         | C        |
+-----------+-----------+----------+

Ce qui ressemble à ceci lorsqu’il est rendu en HTML:

A B C

Notez que les tableaux en grille sont assez difficiles à écrire avec un éditeur de texte simple (parce que contrairement aux tableaux classiques, les indicateurs de colonne doivent être alignés). Voici quelques outils qui peuvent aider à créer des tableaux en grille:

  • Dans Quarto Visual Editor
  • Mode Plain Text du générateur de tableaux avec l’option Utiliser reStructuredText syntax activée

Références