Contribuer à Artmeta¶

Merci de l'intérêt que vous portez à artmeta ! Toutes les contributions, qu'il s'agisse de rapports de bugs, de nouvelles fonctionnalités, d'améliorations de la documentation ou de corrections de coquilles, sont les bienvenues.

Ce guide vous accompagnera dans le processus.

Comment Puis-Je Contribuer ?¶

Rapporter un Bug¶

Si vous pensez avoir trouvé un bug, veuillez ouvrir une nouvelle issue sur GitLab. Assurez-vous d'inclure :

La version d'artmeta que vous utilisez (artmeta --version).
Les étapes exactes pour reproduire le bug.
Le comportement que vous attendiez.
Le comportement que vous avez observé (y compris les messages d'erreur).

Suggérer une Amélioration¶

Pour proposer une nouvelle fonctionnalité ou une amélioration, ouvrez également une issue sur GitLab. Décrivez clairement la fonctionnalité que vous aimeriez voir et pourquoi elle serait utile.

Proposer une Modification (Code ou Documentation)¶

Si vous souhaitez corriger un bug ou implémenter une nouvelle fonctionnalité, suivez le guide ci-dessous.

Votre Première Contribution en Code¶

A. Mettre en place l'environnement de développement¶

Clonez le dépôt :

git clone https://plmlab.math.cnrs.fr/nicolas.klutchnikoff/artmeta.git
cd artmeta

Créez un environnement virtuel :

python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# ou : venv\Scripts\activate pour Windows

Installez les dépendances en mode développement :
```
pip install -e ".[dev]"
```
Cela installe artmeta en mode éditable ainsi que les outils de test et de documentation.

B. Lancer les tests¶

Assurez-vous que tous les tests passent avant de commencer vos modifications et après.

pytest

# Pour obtenir un rapport de couverture de code
pytest --cov=artmeta

C. Respecter le style de code¶

Le code doit être formaté avec black.
Le code doit passer les vérifications de ruff.
Suivez les conventions de nommage (PascalCase pour les classes, snake_case pour les fonctions).
Documentez les fonctions publiques avec des docstrings.

D. Soumettre la contribution (Merge Request)¶

Créez une branche pour vos modifications :

git checkout -b feature/ma-nouvelle-fonctionnalite

Faites vos modifications : code, tests et documentation.

Commitez vos changements avec un message clair :

git add .
git commit -m "feat: Ajout du générateur pour la revue X

- Ajout de la classe XGenerator et du template Jinja2.
- Ajout des tests correspondants."

Poussez votre branche et ouvrez une "Merge Request" sur GitLab.

Guide Technique : Ajouter un Nouveau Générateur¶

C'est la manière la plus courante de contribuer à artmeta. Voici les étapes :

Créez le template Jinja2 dans src/artmeta/templates/. Le nom de fichier doit être monjournal.tex.j2.
- Nous utilisons Jinja2 pour séparer la logique du code LaTeX. Pour un guide détaillé sur sa syntaxe, consultez notre Guide Jinja2.

Créez le fichier Python du générateur dans src/artmeta/generators/, par exemple monjournal.py.

from .base import BaseGenerator

class MonJournalGenerator(BaseGenerator):
    DOCUMENT_CLASS = "monjournal"

    def generate(self) -> str:
        return self.generate_with_template('monjournal.tex.j2')

Enregistrez votre nouveau générateur dans src/artmeta/generators/__init__.py en l'ajoutant au dictionnaire GENERATORS.
Ajoutez des tests pour votre générateur dans le répertoire tests/.

Références Techniques¶

Architecture du Projet¶

L'essentiel du code se trouve dans src/artmeta/ : - core.py: La classe principale ArtMeta. - cli.py: L'interface en ligne de commande. - validators.py: La logique de validation des données. - generators/: Contient les générateurs pour chaque format de sortie. - base.py: La classe de base que chaque générateur doit hériter. - templates/: Les modèles Jinja2 pour la génération de code.

Écrire des Tests¶

Pour un nouveau générateur, créez un fichier tests/test_monjournal.py. Inspirez-vous des tests existants. Utilisez des dictionnaires Python simples pour simuler les métadonnées et vérifiez que la sortie LaTeX générée contient bien les chaînes de caractères attendues.

from artmeta.generators.monjournal import MonJournalGenerator

def test_monjournal_titre():
    meta = {'title': 'Un Titre de Test'}
    gen = MonJournalGenerator(meta)
    latex = gen.generate()
    assert '\title{Un Titre de Test}' in latex