From 7746c226d40718804acd342e1e9fd25e8a3d1968 Mon Sep 17 00:00:00 2001
From: Antoine Van Elstraete <antoine@van-elstraete.net>
Date: Sat, 5 Sep 2026 22:38:54 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20convention=20de=20docstrings=20Sphinx/r?=
 =?UTF-8?q?eST=20pour=20g=C3=A9n=C3=A9ration=20PDF=20via=20LaTeX?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ajout dans la section « Conventions de code » d'AGENTS.md :
- Docstrings obligatoires pour toute fonction, méthode et classe publique
- Format Sphinx/reST (:param, :return:, :rtype:, :raises)
- Docstring de module obligatoire
- Objectif : documentation PDF via Sphinx/LaTeX
- Exemple concret inclus
---
 AGENTS.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index bec6d95..1bcad9c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -126,6 +126,30 @@ pronote-sync --dry-run
   - Si `pronotepy` échoue → fallback vers le parsing **iCal**.
   - Si tout échoue → lever une **erreur explicite**.
 
+### Documentation (docstrings)
+- **Obligatoire** : **Toute** fonction, méthode et classe publique doit avoir une docstring.
+- **Format** : Utiliser le format **Sphinx/reST** (pas Google ou NumPy) pour une compatibilité native avec Sphinx.
+- **Contenu** :
+  - Une ligne de résumé courte (une phrase).
+  - Une description étendue optionnelle.
+  - Les paramètres avec `:param nom:`.
+  - Le retour avec `:return:` et `:rtype:`.
+  - Les exceptions avec `:raises TypeException:`.
+- **Modules** : Chaque module doit avoir une docstring au niveau module.
+- **Objectif** : Générer une **documentation PDF via LaTeX** avec Sphinx.
+
+Exemple :
+```python
+def fetch_ical(url: str) -> str:
+    """Récupère le contenu d'un flux iCal Pronote.
+
+    :param url: URL du flux iCal (avec token ``icalsecurise``).
+    :return: Contenu brut du flux iCal.
+    :rtype: str
+    :raises requests.RequestException: Si la requête HTTP échoue.
+    """
+```
+
 ---
 
 ## 6. Sécurité et secrets