Guide d'Utilisation de Jinja2 pour Artmeta¶

Ce guide vous apprend à créer un template de A à Z pour artmeta en utilisant le moteur de templates Jinja2.

Jinja2 nous permet de séparer la structure du code LaTeX (la présentation) de la logique de génération en Python. Cela rend les modèles de revues plus faciles à lire, à écrire et à maintenir.

1. Les Fondamentaux de Jinja2¶

Il y a trois types de balises principales :

{{ ... }} : Pour afficher le contenu d'une variable.
{% ... %} : Pour exécuter de la logique (conditions, boucles).
{# ... #} : Pour écrire des commentaires qui n'apparaîtront pas dans le fichier final.

Variables et Filtres¶

Pour insérer une donnée, on utilise {{ une_variable }}. On peut la transformer avec un filtre, en utilisant le symbole |.

{# Si meta.keywords est ["maths", "physique"] #}
\keywords{{ '{' }}{{ meta.keywords|join(', ') }}{{ '}' }}

Résultat : \keywords{maths, physique}

Conditions¶

Le bloc {% if %} permet d'afficher du contenu uniquement si une condition est vraie.

{% if meta.title_short %}
  \shorttitle{{ '{' }}{{ meta.title_short }}{{ '}' }}
{% endif %}

Boucles¶

Le bloc {% for %} permet de répéter une section pour chaque élément d'une liste.

{% for author in meta.authors %}
  \author{{ '{' }}{{ author.firstname }} {{ author.lastname }}{{ '}' }}
{% endfor %}

2. Le Contexte Spécifique à `artmeta`¶

Chaque template Jinja2 reçoit automatiquement deux objets principaux :

meta: Un dictionnaire contenant toutes les métadonnées de votre fichier art.yml (meta.title, meta.authors, etc.).
affiliations: Un dictionnaire qui mappe les IDs d'affiliation à l'objet affiliation complet. C'est un raccourci très pratique.

3. Atelier Pratique : Créer un Template Simple¶

Imaginons que nous voulons créer un template pour une revue fictive, myjournal. Voici un exemple de art.yml :

title: "Un article formidable"
authors:
  - firstname: "Alice"
    lastname: "Martin"
    affiliations: [1]
abstract: "Ceci est le résumé."
affiliations:
  - id: 1
    name: "Université Fictive"

Objectif : Créer le template myjournal.tex.j2 pour générer le code LaTeX.

Étape 1 : Le titre C'est le plus simple. On insère la variable meta.title.

\title{{ '{' }}{{ meta.title }}{{ '}' }}

Étape 2 : Les auteurs On boucle sur la liste meta.authors.

{% for author in meta.authors %}
\author{{ '{' }}{{ author.firstname }} {{ author.lastname }}{{ '}' }}
{% endfor %}

Étape 3 : L'affiliation Dans la boucle des auteurs, on utilise le dictionnaire affiliations pour récupérer les détails de l'affiliation via son ID.

{% for author in meta.authors %}
\author{{ '{' }}{{ author.firstname }} {{ author.lastname }}{{ '}' }}
  {% for affil_id in author.affiliations %}
    {% set affil = affiliations[affil_id] %}
\address{{ '{' }}{{ affil.name }}{{ '}' }}
  {% endfor %}
{% endfor %}

Étape 4 : L'abstract (conditionnel) On n'affiche le bloc abstract que si la clé abstract existe dans les métadonnées.

{% if meta.abstract %}
\begin{abstract}
{{ meta.abstract }}
\end{abstract}
{% endif %}

Résultat Final : myjournal.tex.j2

{# Template pour la classe myjournal #}

\title{{ '{' }}{{ meta.title }}{{ '}' }}

{% for author in meta.authors %}
\author{{ '{' }}{{ author.firstname }} {{ author.lastname }}{{ '}' }}
  {% for affil_id in author.affiliations %}
    {% set affil = affiliations[affil_id] %}
\address{{ '{' }}{{ affil.name }}{{ '}' }}
  {% endfor %}
{% endfor %}

{% if meta.abstract %}
\begin{abstract}
{{ meta.abstract }}
\end{abstract}
{% endif %}

\maketitle

4. Techniques Essentielles pour le LaTeX¶

Le Contrôle des Espaces¶

Par défaut, Jinja2 conserve tous les sauts de ligne, ce qui peut créer des espaces vides dans votre LaTeX. Pour un rendu propre, utilisez le modificateur - pour supprimer les espaces avant ou après un bloc.

{%- supprime la ligne vide avant.
-%} supprime la ligne vide après.

{# Mauvais : crée des lignes vides #}
{% if meta.title %}
\title{...}
{% endif %}

{# Bon : compact et propre #}
{%- if meta.title -%}
\title{...}
{%- endif -%}

Conseil : Utilisez {%- et -%} sur presque tous vos blocs de logique.

Échapper les Caractères Spéciaux¶

LaTeX utilise des caractères spéciaux comme &, %, $, _, {, }. Si vos métadonnées (par exemple, le titre) contiennent l'un de ces caractères, la compilation LaTeX échouera. Jinja2 fournit un filtre escape ou e pour les échapper automatiquement.

{# À FAIRE : Implémenter un filtre d'échappement LaTeX #}
{# Exemple : \title{{ '{' }}{{ meta.title | latex_escape }}{{ '}' }} #}

Note : Un filtre latex_escape dédié n'est pas encore fourni par défaut, mais peut être ajouté dans le générateur Python si nécessaire.

5. Pour Aller Plus Loin¶

Macros : Pour des blocs de code réutilisables, comme formater un auteur complexe. Voir {% macro %}.
Variables set : Pour définir des variables intermédiaires dans le template.

Pour tout le reste, la documentation officielle de Jinja2 est votre meilleure amie.