docs: convention de docstrings Sphinx/reST pour génération PDF via LaTeX

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
This commit is contained in:
2026-09-05 22:38:54 +02:00
parent 03a4377f01
commit 7746c226d4

View File

@@ -126,6 +126,30 @@ pronote-sync --dry-run
- Si `pronotepy` échoue → fallback vers le parsing **iCal**. - Si `pronotepy` échoue → fallback vers le parsing **iCal**.
- Si tout échoue → lever une **erreur explicite**. - 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 ## 6. Sécurité et secrets