Dokumentation Best Practices für wissenschaftliche Python-Pakete

Reading Time: 8 minutes

Hervorragende Dokumentation wandelt wissenschaftliche Python-Pakete vom unbrauchbaren Code in reproduzierbare Forschungsressourcen um. Wählen Sie einen Dokumentation-as-Code-Ansatz: Speichern Sie Dokumente neben dem Code, verwenden Sie Sphinx mit Numpy oder Google-Stil-DocStrings, automatisieren Sie Builds mit Lesen Sie die docs und integrieren Sie Dokumentationsaktualisierungen in jede Codeüberprüfung. Schließen Sie eine klare Readme ein, pflegen Sie ein Changelog und testen Sie Beispiele mit DocTest. Behandeln Sie die Dokumentation als erstklassige Leistung, nicht als nachträgliche Idee.

Warum Dokumentation in wissenschaftlicher Python wichtig ist

Wissenschaftliche Software erzielt oft keine Wirkung, nicht aufgrund fehlerhafter Algorithmen, sondern weil andere (oder sogar die ursprünglichen Autoren Monate später) das Werk nicht verstehen oder reproduzieren können. Laut einer Studie zu Best Practices für wissenschaftliche Software ist eine klare Dokumentation für Reproduzierbarkeit, Wartbarkeit und Peer-Validierung von wesentlicher Bedeutung. Im Gegensatz zu kommerzieller Software, bei der die Dokumentation häufig vernachlässigt wird, erfordert der Forschungscode eine besonders sorgfältige Dokumentation, um sicherzustellen, dass Rechenergebnisse vertrauenswürdig und erweitert werden können.

Die Folgen schlechter Dokumentation im wissenschaftlichen Kontext sind:

Unreproduzierbare Ergebnisse aufgrund unklarer Konfiguration
verschwendete Zeit Reverse-Engineering eigener Code Monate später
Unfähigkeit, auf der Arbeit anderer aufzubauen
Fehlgeschlagene Peer-Review der Berechnungsmethoden
Verlassene Projekte, wenn ursprüngliche Entwickler gehen

Eine gute Dokumentation überbrückt die Lücke zwischen mathematischer Formulierung und Arbeitssimulation – die Lücke, die Matforge geschlossen hat.

Die Documentation-as-Code-Philosophie

Der effektivste Dokumentationsansatz in wissenschaftlichen Python-Projekten ist Dokumentation-as-Code (DAC): Behandeln Sie die Dokumentation mit der gleichen Genauigkeit wie den Quellcode. Das bedeutet:

Versionsdokumentation neben Code – Speichern Sie Markdown- oder Restrukturierungstextdateien in einem docs/-Verzeichnis im selben Repository wie Ihr Quellcode. Dadurch wird sichergestellt, dass die Dokumentation immer mit der entsprechenden Codeversion übereinstimmt.
Dokumentation in Pull Requests – Machen Sie die Dokumentationsaktualisierungen obligatorisch für Codeänderungen, die die Funktionalität verändern. Eine Code-Überprüfung ist unvollständig, wenn die Dokumentation nicht aktualisiert wird.
Building and Deployment automatisieren – Verwenden Sie GitHub-Aktionen oder GitLab CI, um bei jedem Push- und Bereitstellungsdienst automatisch Dokumentationen wie Read the Docs zu erstellen.
Wenden Sie die gleichen Qualitätsstandards – Fassen Sie Ihren Markdown, suchen Sie nach defekten Links und behandeln Sie Dokumentationsfehler mit der gleichen Ernsthaftigkeit wie Code-Bugs.

Dieser Ansatz verhindert den häufigsten Dokumentationsfehler: Dokumente, die mit dem von ihnen beschriebenen Code nicht synchron sind.

Das Diátaxis-Framework: vier Dokumentationstypen

Eine wirksame Dokumentation dient unterschiedlichen Zwecken. Das Diátaxis-Framework unterteilt die Dokumentation in vier Kategorien:

1. Tutorials (lernorientiert)

Tutorials sind Schritt-für-Schritt-Lektionen, die Neulinge durch eine vollständige, bedeutungsvolle Aufgabe führen. Sie sollten konkret und praxisnah sein und zu einem Arbeitsergebnis führen. Für wissenschaftliche Python-Pakete können Tutorials Folgendes umfassen:

FIPY für ein einfaches Diffusionsproblem einrichten
Ausführen Ihrer ersten Phasenfeldsimulation
Validierung eines PDE-Solvers gegen eine analytische Lösung

Schlüsselprinzip: Tutorials lehren durch Tun. Vermeiden Sie abstrakte Konzepte; Konzentrieren Sie sich auf praktische Schritte mit sofortigem Feedback.

2. Anleitungen (zielorientiert)

Anleitungen bieten Rezepte für bestimmte Aufgaben. Im Gegensatz zu Tutorials setzen sie grundlegende Vertrautheit voraus und zielen auf ein klares Ziel. Beispiele:

So implementieren Sie benutzerdefinierte Randbedingungen in FIPY
So parallelisieren Sie Ihre Simulation mit MPI
So profilieren und optimieren Sie einen PDE-Solver

Struktur: Stellen Sie ein klares Ziel dar und geben Sie dann nummerierte Schritte oder Code-Snippets an, die es erreichen.

3. Technische Referenz (informationsorientiert)

Die API-Referenzdokumentation beschreibt, was jede Funktion, Klasse und Modul tut. Hier werden umfassende DocStrings kritisch. Die Referenzdokumentation sollte umfassend und präzise sein, sodass erfahrene Benutzer schnell Details nachschlagen können.

4. Erläuterung (verständnisorientiert)

Erläuterungen diskutieren Hintergrund, Designentscheidungen und konzeptionelle Modelle. Sie beantworten „Warum“ Fragen, die Tutorials und Referenzdokumente nicht können. Beispiele:

Warum Finite Volume über Finite-Elemente-Methoden wählen?
Die numerische Stabilität im Zeitschritt verstehen
Die Mathematik hinter Phasenfeldmodellen

Ein gut strukturiertes Dokumentationsset enthält alle vier Typen, jede an der richtigen Stelle.

Einrichten Ihres Dokumentationsstapels

Für wissenschaftliche Python-Pakete ist die De-facto-Standard-Toolchain Sphinx mit Read the Docs-Hosting.

Sphinx: Die Dokumentationsmaschine

Sphinx ist ein leistungsfähiger Dokumentationsgenerator, der restrukturierten Text oder Markdown in professionelle Websites, PDFs und E-Books umwandelt. Seine Hauptmerkmale für wissenschaftliche Software:

Automatische API-Dokumentation – Sphinx kann DocStrings aus Ihrem Python-Code extrahieren und API-Referenzseiten automatisch über die Erweiterung autodoc generieren.
Querverweise – Einfache Verknüpfung zwischen Dokumentationsseiten und externen Projekten.
Mathematische Notation – Unterstützung für Latex-Gleichungen, die mit MathJAX wiedergegeben werden, die für wissenschaftliche Inhalte unerlässlich sind.
Extensible – Hunderte von Erweiterungen für benutzerdefinierte Funktionen.

Zum Einstieg:

pip install sphinx sphinx-rtd-theme
sphinx-quickstart

Konfigurieren Sie conf.py, um den Pfad Ihres Pakets einzuschließen, und aktivieren Sie Erweiterungen wie sphinx.ext.autodoc, sphinx.ext.napoleon (für Google/Numpy DocStrings) und sphinx.ext.mathjax.

Lesen Sie die Dokumente: Kostenloses Hosting mit Automatisierung

Read the Docs ist eine kostenlose Hosting-Plattform für die Sphinx-Dokumentation. Es lässt sich nahtlos in GitHub integrieren:

Verbinden Sie Ihr Repository
Lesen Sie die Dokumente erstellt automatisch eine Dokumentation zu jedem Push
Benutzerdefinierte Domains, Versionsauswahl und PDF-Downloads verfügbar
Unterstützt mehrere Versionen (stabile, neueste, getaggte Versionen)

Diese Automatisierung stellt sicher, dass Ihre Dokumentation immer auf dem neuesten Stand Ihres Codes ist.

Auswahl eines DocString-Formats: Numpy vs Google

DocStrings sind die Grundlage der API-Dokumentation. Drei Formate dominieren Python:

Format	Eigenschaften	Wissenschaftliche Präferenz
ruhe	Original-Sphinx-Format, verwendet `:param name: description` Syntax	Legacy-Projekte
Google	Sauberes, minimales Markup; Abschnitte mit einfachen Headern	Moderne Projekte, General Python
Numpy	Strukturierte Abschnitte mit Unterstrichen; Hervorragend für komplexe Signaturen	Wissenschaftliche Python

Der Numpy-Stil ist in wissenschaftlichen Paketen am häufigsten, da das strukturierte Format mehrere Parameter, Returns und komplexe Typannotationen klar verarbeitet. Der Scientific Python-Entwicklungshandbuch empfiehlt Numpy-Style zu seiner Klarheit.

Beispiel: numpy-string docstring

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}")
    """

Die Sphinx-Erweiterung napoleon analysiert sowohl Google- als auch Numpy-Stile. Wählen Sie sie daher basierend auf den Vorlieben Ihres Teams aus.

effektive DocStrings schreiben

Effektive DocStrings folgen konsistenten Konventionen und liefern vollständige Informationen. PyOpenSci-Dokumentation Leitfaden umreißt wesentliche Abschnitte:

Erforderliche Abschnitte

Summary Line – Ein Satz beschreibt, was die Funktion bewirkt.
Parameter – Name, Typ und Beschreibung für jedes Argument.
Returns – Typ und Beschreibung der Rückgabewerte.
Erhöhungen – Ausnahmen, die ausgelöst werden können.

Optionale, aber wertvolle Abschnitte

Beispiele – Snippets für konkrete Nutzung; Diese können mit DOCTEST getestet werden.
Notes – Implementierungsdetails, Algorithmusreferenzen, Leistungsmerkmale.
Referenzen – Zitate zu Papieren oder externen Dokumentationen.
Siehe auch – Links zu verwandten Funktionen oder Klassen.

Die Kraft der Beispiele

Beispiele dienen doppelten Zwecken:

Sie zeigen den Benutzern, wie Sie Ihren Code anwenden können.
Sie werden über doctest ausführbare Tests.

Wenn Beispiele als interaktive Python-Sitzungen geschrieben werden, können sowohl Benutzer als auch automatisierte Tools überprüfen, ob sie ordnungsgemäß funktionieren. Dies schützt vor Dokumentationsfäulnis.

Testdokumentation mit DOCTEST

DocTest ist ein Python-Modul, das Codebeispiele in DocStrings überprüft und die erwartete Ausgabe erzeugt. Dadurch entsteht eine lebendige Dokumentation, die nicht stillschweigend falsch werden kann.

So geht’s: Sie schreiben ein Beispiel, als ob sie an einer Python-Eingabeaufforderung eingegeben wurden:

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

Die Ausführung von pytest --doctest-module oder python -m doctest -v your_module.py führt diese Beispiele aus und schlägt fehl, wenn die Ausgabe abweicht.

Für wissenschaftliche Pakete ist DOCTEST besonders wertvoll, weil:

Numerischer Code kann leicht zu falschen Ergebnissen führen, ohne Fehler zu verursachen. DocTest fängt stille Ungenauigkeiten auf.
Beispiele zeigen die richtigen Nutzungsmuster (Einheiten, Randbedingungen usw.).
Sie dienen als minimale Regressionstests für die Kernfunktionalität.

Das pytest-doctestplus-Plugin von Scientific Python bietet erweiterte Funktionen für das Testen der Dokumentation.

Die Readme: Die Haustür Ihres Projekts

Die Readme ist oft die erste und manchmal nur – Dokumentierung, auf die Benutzer stoßen. Eine gut gestaltete Readme sollte an der Wurzel Ihres Repository und auf Pypi erscheinen.

Essential Readme-Abschnitte:

Projektbeschreibung – 1-3 Sätze, die erklären, was das Paket tut und welche Domäne.
Installationsanweisungen – So installieren Sie, einschließlich Abhängigkeiten und Plattformanforderungen.
Quick-Beispiel – Minimaler Code-Snippet, der einen typischen Anwendungsfall zeigt.
Links zur vollständigen Dokumentation – Direkte Benutzer zu umfassenden Dokumenten, die an anderer Stelle gehostet werden.
Zitatinformationen – So zitieren Sie die Software in der akademischen Arbeit.
Lizenz – Geben Sie die Lizenz eindeutig an (z. B. MIT, BSD, GPL).
Badges – Build-Status, Abdeckung, Pypi-Version usw.

Das pyopensci Readme-Guide enthält detaillierte Empfehlungen.

Pro-Tipp: Schreiben Sie Ihre Readme, bevor Sie einen Code schreiben. Dies verdeutlicht die Ziele und das Publikum Ihres Projekts.

Pflege eines Changelogs

Ein Changelog ist eine chronologische Liste bemerkenswerter Änderungen für jede Version. Es antwortet „Was hat sich zwischen Version X und Y geändert?“ Für Benutzer und Entwickler.

Best Practices:

Befolgen Sie Konventionen für Changelog .
Verwenden Sie Semantische Versionierung , um die Kompatibilität zu kommunizieren.
Gruppenänderungen nach Typ: Added, Changed, Deprecated, Removed, Fixed, Security.
Schreiben Sie für Menschen: Erklären Sie, warum eine Veränderung wichtig ist, nicht nur, dass es passiert ist.
Geben Sie Daten für unveröffentlichte Änderungen an.
Automatisieren Sie niemals nur Git Commit-Nachrichten – kuratieren Sie die Einträge.

Beispielformat:

## [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).

Ein gutes Changelog schafft Vertrauen, indem es aktive Wartung und Transparenz über das Brechen von Änderungen zeigt.

Häufige Dokumentationsstöße (und wie man sie vermeidet)

Aufgrund der Literatur und der Community-Erfahrung sind hier häufige Fehler:

1. Veraltete Dokumentation

Dokumentation, die dem tatsächlichen Verhalten widerspricht, ist schlimmer als keine Dokumentation. Lösung: Integrieren Sie Dokumentationsaktualisierungen in Code-Überprüfungen. Wenn ein PR die Funktionalität ändert, müssen die entsprechenden Dokumente im selben Commit aktualisiert werden.

2. Fehlende Beispiele

Abstrakte Beschreibungen ohne konkrete Verwendungsbeispiele lassen die Benutzer raten. Lösung: Jede öffentliche Funktion und Klasse sollte mindestens ein lauffähiges Beispiel enthalten.

3. Erklären „Was“, aber nicht „Warum“

Die Dokumentation beschreibt oft die Mechanik, lässt aber die Argumentation aus. Benutzer müssen den Kontext verstehen, um richtige Entscheidungen zu treffen. Lösung: Enthält Abschnitte, in denen erklärt wird, wann eine Funktion verwendet werden soll, Kompromisse und Alternativen.

4. Nichtübereinstimmung des Publikums

Schreiben für Experten, wenn Anfänger das Hauptpublikum sind (oder umgekehrt). Lösung: Strukturieren Sie Ihre Dokumente mithilfe des Diátaxis-Frameworks, um unterschiedliche Bedürfnisse separat zu bedienen.

5. Inkonsistenter Stil

Gemischte DocString-Formate, unterschiedliche Überschriftenstufen und Ad-hoc-Organisation. Lösung: Nehmen Sie einen Styleguide an und erzwingen Sie ihn mit LINTERS (markdownlint, doc8).

6. Keine Prüfung

Ungetestete Beispiele brechen schließlich. Lösung: Verwenden Sie doctest oder pytest-doctestplus, um alle Beispiele zu überprüfen.

7. Vernachlässigung der Readme

Angenommen, Benutzer lesen umfangreiche Anleitungen, bevor Sie das Paket ausprobieren. Lösung: Machen Sie die Readme überzeugend und umsetzbar; Fügen Sie einen Schnellstartabschnitt hinzu.

Dokumentation Workflow-Integration

Die Dokumentation sollte natürlich mit Ihrem Entwicklungsprozess fließen:

Haken vorbefestigen

Verwenden Sie Pre-Commit-Hooks, um Markdown zu versorgen, und prüfen Sie nach häufigen Problemen, bevor Sie Commits zulassen:

# .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

CI/CD-Pipelines

Konfigurieren Sie GitHub-Aktionen auf:

Erstellen Sie eine Dokumentation zu jedem Push zum Main
Bereitstellen, um die Dokumente automatisch zu lesen
Führen Sie doctest als Teil der Testsuite aus
Suchen Sie nach defekten Links im erstellten HTML

Beispielworkflow:

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

Code-Bewertungen

Machen Sie die Dokumentation zur Überprüfung einer Checklistenposition:

Neue/geänderte Funktionen haben docStrings
Beispiele sind enthalten und getestet
README wird aktualisiert, wenn benutzerseitige Änderungen aufgetreten sind
Änderungsprotokolleintrag für Version Bump hinzugefügt

Machen Sie Ihre Dokumentation zitierbar

Wissenschaftliche Software sollte als Forschungsartefakt zitierbar sein. gehören:

Citation.cff – Eine Standard-Citation.cff-Datei im Repository-Stamm mit Citation-Metadaten (Autoren, Titel, Version, DOI).
Zenodo-Integration – Verbinden Sie Ihr GitHub-Repository mit Zenodo, um DOIs für jede Version automatisch zuzuweisen.
Anleitung zur Software-Zitierung – Fügen Sie Ihrer Readme-Datei einen Abschnitt „Zitat“ und die Dokumentation zu BibTex-Einträgen hinzu.

Dies stellt sicher, dass Ihre Arbeit akademische Kredite erhält und die Anforderungen an die Reproduzierbarkeit von Zeitschriften und Förderagenturen erfüllt.

Interne Verlinkung und Weiterlesen

Mehr zu verwandten Themen:

Diese Artikel behandeln ergänzende Aspekte der Entwicklung von Software für nachhaltige Forschung.

Fazit und nächste Schritte

Die Dokumentation ist keine sekundäre Aufgabe – sie ist das Fahrzeug, durch das Ihr wissenschaftliches Python-Paket Wirkung erzielt. Indem Sie die Dokumentation als Code verwenden, die richtige Toolchain (Sphinx + Read the Docs) verwenden, strukturierte Frameworks wie Diátaxis folgen und die Dokumentation in Ihren Entwicklungsworkflow integrieren, erstellen Sie eine Software, die wirklich wiederverwendbar und reproduzierbar ist.

Heute zu implementierende Aktionselemente:

Stellen Sie sicher, dass jede öffentliche Funktion und Klasse einen DocString im Numpy- oder Google-Stil hat.
Richten Sie ein docs/-Verzeichnis mit Sphinx-Konfiguration ein.
Verbinden Sie Ihr Repository, um die Dokumente für automatisierte Builds zu lesen.
Fügen Sie DocTest zu Ihrer CI-Pipeline hinzu, um Beispiele zu überprüfen.
Schreiben oder verbessern Sie Ihre Readme mit einer klaren Beschreibung und einem schnellen Beispiel.
Starten Sie ein Änderungsprotokoll, wenn Sie keine haben.

Dokumente als Investition behandeln: Die Zeit, die Sie damit verbringen, klare Dokumente zu schreiben, zahlt sich aus, wenn es um die geringere Unterstützungslast, die breitere Akzeptanz und die langfristige Wartbarkeit Ihrer wissenschaftlichen Software geht.

Weitere Ressourcen: