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:
24
AGENTS.md
24
AGENTS.md
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user