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 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
|
||||
|
||||
Reference in New Issue
Block a user