Meilleures pratiques de documentation pour les packages scientifiques Python

Une excellente documentation transforme les packages Scientific Python d’un code inutilisable en ressources de recherche reproductibles. Adoptez une approche Documentation-as-code : stockez les documents avec le code, utilisez Sphinx avec numpy ou google-style docstrings, automatisez les builds avec Lire le docs et intégrer les mises à jour de la documentation à chaque examen de code. Incluez un Readme clair, maintenez un Changelog et testez des exemples avec Doctest. Traitez la documentation comme un livrable de première classe, et non comme une réflexion après coup.

Pourquoi la documentation est-elle importante en Python scientifique

Les logiciels scientifiques ne parviennent souvent pas à obtenir un impact non pas en raison d’algorithmes défectueux, mais parce que d’autres (ou même les auteurs originaux des mois plus tard) ne peuvent pas comprendre ou reproduire l’œuvre. Selon une étude des meilleures pratiques de logiciels scientifiques, une documentation claire est essentielle pour la reproductibilité, la maintenabilité et la validation par les pairs. Contrairement aux logiciels commerciaux où la documentation est souvent négligée, le code de recherche nécessite une documentation particulièrement soignée pour garantir que les résultats informatiques puissent être approuvés et étendus.

Les conséquences d’une mauvaise documentation dans des contextes scientifiques comprennent :

• Résultats irréproductibles dus à une configuration peu claire
• Perte de temps de rétro-ingénierie de son propre code des mois plus tard
• Incapacité à s’appuyer sur le travail des autres
• Échec de l’examen par les pairs des méthodes de calcul
• Projets abandonnés lorsque les développeurs originaux partent

Une bonne documentation comble le fossé entre la formulation mathématique et la simulation de travail – l’objectif même que Matforge vise à combler.

La philosophie de la documentation comme code

L’approche la plus efficace de la documentation dans les projets scientifiques Python est la Documentation-as-Code (DAC) : traitez la documentation avec la même rigueur que le code source. Cela signifie :

1. Documentation de version avec code – Stockez les fichiers Markdown ou RestructuredText dans un répertoire docs/ dans le même référentiel que votre code source. Cela garantit que la documentation correspond toujours à la version de code correspondante.
2. Revoyez la documentation dans les requêtes d’extraction – Rendre les mises à jour de la documentation obligatoires pour tout changement de code qui modifie la fonctionnalité. Une révision du code est incomplète si la documentation n’est pas mise à jour.
3. Automate Construction et déploiement – Utilisez les actions GitHub ou GitLab CI pour créer automatiquement une documentation sur chaque push et déploiement sur des services d’hébergement tels que Read the Docs.
4. Appliquez les mêmes normes de qualité – appliquez votre démarque, recherchez les liens brisés et traitez les bogues de documentation avec le même sérieux que les bogues de code.

Cette approche évite les défaillances de documentation les plus courantes : des documents qui se désynchronisent avec le code qu’ils décrivent.

Le cadre Diátaxis : quatre types de documentation

Une documentation efficace a des objectifs distincts. Le cadre Diátaxis divise la documentation en quatre catégories :

1. Tutoriels (orienté vers l’apprentissage)

Les didacticiels sont des leçons étape par étape qui guident les nouveaux arrivants dans une tâche complète et significative. Ils doivent être concrets, pratiques et aboutir à un résultat de travail. Pour les packages scientifiques Python, les didacticiels peuvent inclure :

• Configuration de Fipy pour un problème de diffusion simple
• Exécution de votre première simulation de champ de phase
• Validation d’un solveur PDE par rapport à une solution analytique

Principe clé : Les tutoriels enseignent en faisant. Évitez les concepts abstraits ; Concentrez-vous sur les étapes pratiques avec une rétroaction immédiate.

2. Guides pratiques (orienté vers les objectifs)

Les guides pratiques fournissent des recettes pour des tâches spécifiques. Contrairement aux didacticiels, ils assument la familiarité de base et visent un objectif clair. Exemples :

• Comment implémenter des conditions aux limites personnalisées dans Fipy
• Comment paralléliser votre simulation avec MPI
• Comment profiler et optimiser un solveur PDE

structure : présente un objectif clair, puis fournissez des étapes numérotées ou des extraits de code qui y parviennent.

3. Référence technique (orientée vers l’information)

La documentation de référence API décrit ce que font chaque fonction, classe et module. C’est là que les doctrings complets deviennent critiques. La documentation de référence doit être exhaustive et précise, permettant aux utilisateurs expérimentés de rechercher rapidement les détails.

4. Explication (orientée vers la compréhension)

Les explications discutent des antécédents, des décisions de conception et des modèles conceptuels. Ils répondent aux questions « pourquoi » que les didacticiels et les documents de référence ne peuvent pas. Exemples :

• Pourquoi choisir le volume fini plutôt que les méthodes d’éléments finis ?
• Comprendre la stabilité numérique dans le temps
• Les mathématiques derrière les modèles de champ de phase

Un ensemble de documentation bien structuré comprend les quatre types, chacun à sa place.

Configurer votre pile de documentation

Pour les packages Scientific Python, la chaîne d’outils standard de facto est Sphinx avec lire les documents.

Sphinx : le moteur de documentation

Sphinx est un puissant générateur de documentation qui transforme RestructuredText ou Markdown en sites Web professionnels, PDF et livres électroniques. Ses principales fonctionnalités pour les logiciels scientifiques :

• Documentation automatique de l’API – Sphinx peut extraire des docstrings de votre code Python et générer automatiquement des pages de référence d’API via l’extension autodoc.
• Références croisées – Lien entre les pages de documentation et les projets externes facilement.
• Notation mathématique – Prise en charge des équations de latex rendues avec MathJax, essentielles pour le contenu scientifique.
• Extensible – des centaines d’extensions pour des fonctionnalités personnalisées.

Pour commencer :

pip install sphinx sphinx-rtd-theme
sphinx-quickstart

Configurez conf.py pour inclure le chemin d’accès de votre package et activer les extensions telles que sphinx.ext.autodoc, sphinx.ext.napoleon (pour Google/NumPy DocStrings) et sphinx.ext.mathjax.

Lire les documents : hébergement gratuit avec automatisation

Lire les documents est une plate-forme d’hébergement gratuite pour la documentation Sphinx. Il s’intègre parfaitement à GitHub :

• Connectez votre référentiel
• Lire les documents construits automatiquement la documentation sur chaque push
• Domaines personnalisés, sélection de versions et téléchargements PDF disponibles
• Prend en charge plusieurs versions (stables, dernières versions taguées)

Cette automatisation garantit que votre documentation est toujours à jour avec votre code.

Choisir un format DocString : NumPy vs Google

Les docstrings sont la base de la documentation de l’API. Trois formats dominent Python :

Le Style Numpy est le plus courant dans les packages scientifiques, car son format structuré gère clairement plusieurs paramètres, retours et annotations de type complexe. Le guide de développement python scientifique recommande NumPy-Style pour sa clarté.

Exemple : docstring de style numpy

def solve_poisson(potential, conductivity, tolerance=1e-6):
    """
    Solve the Poisson equation ∇·(σ∇φ) = 0 using finite volumes.

    Parameters
    ----------
    potential : ndarray
        Initial guess for potential field (will be overwritten).
    conductivity : ndarray
        Conductivity array on cell centers.
    tolerance : float, optional
        Convergence criterion for residual (default: 1e-6).

    Returns
    -------
    residual : float
        Final residual after convergence.

    Notes
    -----
    Uses a conjugate gradient solver with Jacobi preconditioner.
    Boundary conditions must be applied before calling.

    Examples
    --------
    >>> phi = np.zeros(grid.shape)
    >>> sigma = np.ones(grid.shape)
    >>> residual = solve_poisson(phi, sigma)
    >>> print(f"Converged to {residual:.2e}")
    """

L’extension napoleon Sphinx analyse les styles Google et NumPy, alors choisissez en fonction des préférences de votre équipe.

Rédiger des doctrings efficaces

Des doctrings efficaces suivent des conventions cohérentes et fournissent des informations complètes. La documentation pyopensci Guide décrit les sections essentielles :

Sections obligatoires

• Ligne résumée – une phrase décrivant ce que fait la fonction.
• Paramètres – nom, type et description pour chaque argument.
• Rendements – Type et description de la ou des valeurs de retour.
• Suppressions – exceptions qui peuvent être levées et les conditions.

Sections facultatives mais précieuses

• Exemples – extraits d’usage concrets ; Ceux-ci peuvent être testés avec Doctest.
• Notes – Détails de l’implémentation, références d’algorithme, caractéristiques de performances.
• Références – citations à des documents ou à une documentation externe.
• Voir aussi – Liens vers des fonctions ou classes connexes.

Le pouvoir des exemples

Les exemples servent à deux fins :

1. Ils montrent aux utilisateurs comment appliquer votre code.
2. Ils deviennent des tests exécutables via doctest.

Lorsque des exemples sont écrits sous forme de sessions Python interactives, les utilisateurs et les outils automatisés peuvent vérifier qu’ils fonctionnent correctement. Cela protège de la pourriture de la documentation.

Tester la documentation avec DocTest

doctest est un module Python qui vérifie les exemples de code dans DocStrings qui s’exécutent et produisent la sortie attendue. Cela crée une documentation vivante qui ne peut pas devenir silencieusement incorrecte.

Comment ça marche : Vous écrivez un exemple comme s’il était entré à une invite Python :

>>> from mypackage import compute_diffusion
>>> result = compute_diffusion(concentration=1.0, D=0.01)
>>> round(result, 4)
0.1234

L’exécution de pytest --doctest-module ou python -m doctest -v your_module.py exécute ces exemples et échoue si la sortie diffère.

Pour les packages scientifiques, DocTest est particulièrement utile car :

• Le code numérique peut facilement produire des résultats erronés sans provoquer d’erreurs ; Doctest attrape des inexactitudes silencieuses.
• Les exemples illustrent des modèles d’utilisation appropriés (unités, conditions aux limites, etc.).
• Ils servent de tests de régression minimes pour la fonctionnalité de base.

Le plugin pytest-doctestplus de Scientific Python fournit des fonctionnalités améliorées pour tester la documentation.

The Readme : la porte d’entrée de votre projet

Le README est souvent le premier, et parfois le seul, que les utilisateurs de documents rencontrent. Un readme bien conçu devrait apparaître à la racine de votre référentiel et sur Pypi.

Sections de lecture de l’essentiel :

1. Description du projet – 1-3 phrases expliquant ce que fait le package et son domaine.
2. Instructions d’installation – Comment installer, y compris les dépendances et les exigences de la plate-forme.
3. Exemple rapide – Extrait de code minimal montrant un cas d’utilisation typique.
4. Liens vers une documentation complète – dirigez les utilisateurs vers des documents complets hébergés ailleurs.
5. Informations sur les citations – Comment citer le logiciel dans le travail académique.
6. Licence – Indiquez clairement la licence (par exemple, MIT, BSD, GPL).
7. Badges – Statut de construction, couverture, version Pypi, etc.

Le pyopensci readme Guide fournit des recommandations détaillées.

Conseil de pro : Écrivez votre fichier Lisez-moi avant d’écrire un code. Cela clarifie les objectifs et le public de votre projet.

Maintien d’un journal des modifications

Un journal des modifications est une liste chronologique des changements notables pour chaque version. Il répond « Qu’est-ce qui a changé entre la version X et Y ? » tant pour les utilisateurs que pour les développeurs.

Meilleures pratiques :

• Suivez les conservez un changement de journal.
• Utilisez version sémantique pour communiquer la compatibilité.
• Changements de groupe par type : Added, Changed, Deprecated, Removed, Fixed, Security.
• Écrivez pour les humains : expliquez pourquoi un changement est important, pas seulement que cela s’est produit.
• Inclure les dates des modifications non publiées.
• N’automatisez jamais les messages de validation de Git seuls : organisez les entrées.

Format d’exemple :

## [Unreleased]
### Added
- New `adaptive_mesh` module for dynamic refinement.
- Support for HDF5 output with compression.

### Changed
- `solve()` now returns residual history (breaking change).

### Fixed
- Memory leak in sparse matrix assembly (#123).

Un bon journal des modifications renforce la confiance en affichant une maintenance active et une transparence sur la rupture des modifications.

Les pièges de la documentation courante (et comment les éviter)

Sur la base de la littérature et de l’expérience de la communauté, voici des erreurs fréquentes :

1. Documentation obsolète

Une documentation qui contredit le comportement réel est pire que aucune documentation. Solution : Intégrez les mises à jour de la documentation dans les revues de code. Si un PR modifie la fonctionnalité, les documents correspondants doivent être mis à jour dans le même commit.

2. Exemples manquants

Des descriptions abstraites sans exemples d’utilisation concrète laissent les utilisateurs deviner. Solution : Chaque fonction publique et classe doivent inclure au moins un exemple exécutable.

3. Expliquer « quoi » mais pas « pourquoi »

La documentation décrit souvent la mécanique mais omet le raisonnement. Les utilisateurs doivent comprendre le contexte pour prendre des décisions correctes. Solution : Incluez des sections expliquant quand utiliser une fonction, des compromis et des alternatives.

4. Incompatibilité du public

Écrire pour les experts lorsque les débutants sont le public principal (ou vice versa). Solution : Structurez vos documents à l’aide du framework Diátaxis pour répondre aux différents besoins séparément.

5. Style incohérent

Formats de docstring mixtes, niveaux de titre variables et organisation ad hoc. Solution : Adoptez un guide de style et appliquez-le avec des linters (markdownlint, doc8).

6. Aucun test

Les exemples non testés finissent par se casser. Solution : Utilisez doctest ou pytest-doctestplus pour vérifier que tous les exemples fonctionnent.

7. Négliger le Lisez-moi

En supposant que les utilisateurs liront de nombreux guides avant d’essayer le package. Solution : rend le Lisez-moi convaincant et exploitable ; Inclure une section de démarrage rapide.

Intégration du flux de travail

La documentation doit circuler naturellement avec votre processus de développement :

Crochets de pré-commit

Utilisez des crochets de pré-commit pour peloter le démarque et vérifier les problèmes courants avant d’autoriser les validations :

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/markdownlint/markdownlint
    rev: v0.11.0
    hooks:
      - id: markdownlint
  - repo: https://github.com/antonbabenko/pre-commit-docs
    rev: v1.6.0
    hooks:
      - id: check-links

Pipelines CI/CD

Configurez les actions GitHub pour :

• Créez une documentation sur chaque poussée vers le principal
• Déployer pour lire les documents automatiquement
• Exécuter doctest dans le cadre de la suite de tests
• Vérifiez les liens brisés dans le code HTML construit

Exemple de workflow :

name: Documentation
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build docs
        run: |
          pip install -e .[docs]
          sphinx-build -b html docs/ docs/_build/html

Avis de code

Faire passer la documentation en revue un élément de la liste de contrôle :

• Les fonctions nouvelles/modifiées ont des doctrings
• Des exemples sont inclus et testés
• Lisez-moi est mis à jour si des modifications sont survenues
• Entrée de journal des modifications ajoutée pour la version bosse

Rendre votre documentation citée

Les logiciels scientifiques doivent être cités comme un artefact de recherche. Inclure :

• citation.cff – Un fichier citation.cff standard dans la racine du référentiel avec des métadonnées de citation (auteurs, titre, version, doi).
• Intégration Zenodo – Connectez votre référentiel GitHub à ZeNoDo pour attribuer automatiquement des DOI pour chaque version.
• Instructions de citation des logiciels – Ajoutez une section « citation » à votre lecture et documentation affichant des entrées BibTeX.

Cela garantit que votre travail reçoit des crédits académiques et répond aux exigences de reproductibilité des revues et des agences de financement.

Lien interne et lectures complémentaires

Pour en savoir plus sur les sujets connexes :

• Comprendre la simulation scientifique et son rôle dans la recherche
• Suivi de la dette technique à long terme dans les logiciels de recherche
• Gestion des logiciels de recherche par tickets
• Reproductibilité et son rôle dans le débogage

Ces articles couvrent des aspects complémentaires du développement de logiciels de recherche durable.

Conclusion et prochaines étapes

La documentation n’est pas une tâche secondaire, c’est le véhicule par lequel votre package scientifique Python a un impact. En adoptant la documentation comme code, en utilisant la bonne chaîne d’outils (Sphinx + Lire les documents), en suivant des cadres structurés comme Diátaxis et en intégrant la documentation dans votre flux de travail de développement, vous créez des logiciels vraiment réutilisables et reproductibles.

Éléments d’action à mettre en œuvre aujourd’hui :

1. Assurez-vous que chaque fonction publique et classe possède une docstring dans le style NumPy ou Google.
2. Configurez un répertoire docs/ avec la configuration Sphinx.
3. Connectez votre référentiel pour lire les documents pour les builds automatisés.
4. Ajoutez DocTest à votre pipeline CI pour vérifier des exemples.
5. Écrivez ou améliorez votre lisez-moi avec une description claire et un exemple rapide.
6. Démarrez un journal des modifications si vous n’en avez pas.

Traitez la documentation comme un investissement : le temps que vous consacrez à la rédaction de documents clairs rapportera des dividendes dans une charge de soutien réduite, une adoption plus large et une maintenabilité à long terme de votre logiciel scientifique.

Autres ressources :

• Guide de développement scientifique de Python : documentation
• Guide du package Pyopensci Python : documentation
• Dix règles simples pour documenter les logiciels scientifiques
• Documentation Sphinx
• Lire les documents : Documentation pour les projets open source