{"id":845,"date":"2026-07-30T12:22:26","date_gmt":"2026-07-30T12:22:26","guid":{"rendered":"https:\/\/matforge.org\/?p=845","raw":"https:\/\/matforge.org\/?p=845"},"modified":"2026-07-30T12:22:26","modified_gmt":"2026-07-30T12:22:26","slug":"documentation-best-practices-scientific-python-packages","status":"publish","type":"post","link":"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/","title":{"rendered":"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete","raw":"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete"},"content":{"rendered":"<span class=\"span-reading-time rt-reading-time\" style=\"display: block;\"><span class=\"rt-label rt-prefix\">Reading Time: <\/span> <span class=\"rt-time\"> 8<\/span> <span class=\"rt-label rt-postfix\">minutes<\/span><\/span><p>Hervorragende Dokumentation wandelt wissenschaftliche Python-Pakete vom unbrauchbaren Code in reproduzierbare Forschungsressourcen um. W\u00e4hlen Sie einen <strong>Dokumentation-as-Code<\/strong>-Ansatz: Speichern Sie Dokumente neben dem Code, verwenden Sie <strong>Sphinx<\/strong> mit <strong>Numpy oder Google-Stil-DocStrings<\/strong>, automatisieren Sie Builds mit <strong>Lesen Sie die docs <\/strong> und integrieren Sie Dokumentationsaktualisierungen in jede Code\u00fcberpr\u00fcfung. Schlie\u00dfen Sie eine klare <strong>Readme<\/strong> ein, pflegen Sie ein <strong>Changelog<\/strong> und testen Sie Beispiele mit <strong>DocTest<\/strong>. Behandeln Sie die Dokumentation als erstklassige Leistung, nicht als nachtr\u00e4gliche Idee.<\/p>\n<h2>Warum Dokumentation in wissenschaftlicher Python wichtig ist<\/h2>\n<p>Wissenschaftliche Software erzielt oft keine Wirkung, nicht aufgrund fehlerhafter Algorithmen, sondern weil andere (oder sogar die urspr\u00fcnglichen Autoren Monate sp\u00e4ter) das Werk nicht verstehen oder reproduzieren k\u00f6nnen. Laut einer Studie zu Best Practices f\u00fcr wissenschaftliche Software ist eine klare Dokumentation f\u00fcr Reproduzierbarkeit, Wartbarkeit und Peer-Validierung von wesentlicher Bedeutung. Im Gegensatz zu kommerzieller Software, bei der die Dokumentation h\u00e4ufig vernachl\u00e4ssigt wird, erfordert der Forschungscode eine besonders sorgf\u00e4ltige Dokumentation, um sicherzustellen, dass Rechenergebnisse vertrauensw\u00fcrdig und erweitert werden k\u00f6nnen.<\/p>\n<p>Die Folgen schlechter Dokumentation im wissenschaftlichen Kontext sind:<\/p>\n<ul>\n<li>Unreproduzierbare Ergebnisse aufgrund unklarer Konfiguration<\/li>\n<li>verschwendete Zeit Reverse-Engineering eigener Code Monate sp\u00e4ter<\/li>\n<li>Unf\u00e4higkeit, auf der Arbeit anderer aufzubauen<\/li>\n<li>Fehlgeschlagene Peer-Review der Berechnungsmethoden<\/li>\n<li>Verlassene Projekte, wenn urspr\u00fcngliche Entwickler gehen<\/li>\n<\/ul>\n<p>Eine gute Dokumentation \u00fcberbr\u00fcckt die L\u00fccke zwischen mathematischer Formulierung und Arbeitssimulation &#8211; die L\u00fccke, die Matforge geschlossen hat.<\/p>\n<h2>Die Documentation-as-Code-Philosophie<\/h2>\n<p>Der effektivste Dokumentationsansatz in wissenschaftlichen Python-Projekten ist <strong>Dokumentation-as-Code<\/strong> (DAC): Behandeln Sie die Dokumentation mit der gleichen Genauigkeit wie den Quellcode. Das bedeutet:<\/p>\n<ol>\n<li><strong>Versionsdokumentation neben Code<\/strong> \u2013 Speichern Sie Markdown- oder Restrukturierungstextdateien in einem <code>docs\/<\/code>-Verzeichnis im selben Repository wie Ihr Quellcode. Dadurch wird sichergestellt, dass die Dokumentation immer mit der entsprechenden Codeversion \u00fcbereinstimmt.<\/li>\n<li><strong>Dokumentation in Pull Requests<\/strong> \u2013 Machen Sie die Dokumentationsaktualisierungen obligatorisch f\u00fcr Code\u00e4nderungen, die die Funktionalit\u00e4t ver\u00e4ndern. Eine Code-\u00dcberpr\u00fcfung ist unvollst\u00e4ndig, wenn die Dokumentation nicht aktualisiert wird.<\/li>\n<li><strong>Building and Deployment automatisieren<\/strong> \u2013 Verwenden Sie GitHub-Aktionen oder GitLab CI, um bei jedem Push- und Bereitstellungsdienst automatisch Dokumentationen wie Read the Docs zu erstellen.<\/li>\n<li><strong>Wenden Sie die gleichen Qualit\u00e4tsstandards<\/strong> \u2013 Fassen Sie Ihren Markdown, suchen Sie nach defekten Links und behandeln Sie Dokumentationsfehler mit der gleichen Ernsthaftigkeit wie Code-Bugs.<\/li>\n<\/ol>\n<p>Dieser Ansatz verhindert den h\u00e4ufigsten Dokumentationsfehler: Dokumente, die mit dem von ihnen beschriebenen Code nicht synchron sind.<\/p>\n<h2>Das Di\u00e1taxis-Framework: vier Dokumentationstypen<\/h2>\n<p>Eine wirksame Dokumentation dient unterschiedlichen Zwecken. Das Di\u00e1taxis-Framework unterteilt die Dokumentation in vier Kategorien:<\/p>\n<h3>1. Tutorials (lernorientiert)<\/h3>\n<p>Tutorials sind Schritt-f\u00fcr-Schritt-Lektionen, die Neulinge durch eine vollst\u00e4ndige, bedeutungsvolle Aufgabe f\u00fchren. Sie sollten konkret und praxisnah sein und zu einem Arbeitsergebnis f\u00fchren. F\u00fcr wissenschaftliche Python-Pakete k\u00f6nnen Tutorials Folgendes umfassen:<\/p>\n<ul>\n<li>FIPY f\u00fcr ein einfaches Diffusionsproblem einrichten<\/li>\n<li>Ausf\u00fchren Ihrer ersten Phasenfeldsimulation<\/li>\n<li>Validierung eines PDE-Solvers gegen eine analytische L\u00f6sung<\/li>\n<\/ul>\n<p><strong>Schl\u00fcsselprinzip:<\/strong> Tutorials lehren durch Tun. Vermeiden Sie abstrakte Konzepte; Konzentrieren Sie sich auf praktische Schritte mit sofortigem Feedback.<\/p>\n<h3>2. Anleitungen (zielorientiert)<\/h3>\n<p>Anleitungen bieten Rezepte f\u00fcr bestimmte Aufgaben. Im Gegensatz zu Tutorials setzen sie grundlegende Vertrautheit voraus und zielen auf ein klares Ziel. Beispiele:<\/p>\n<ul>\n<li>So implementieren Sie benutzerdefinierte Randbedingungen in FIPY<\/li>\n<li>So parallelisieren Sie Ihre Simulation mit MPI<\/li>\n<li>So profilieren und optimieren Sie einen PDE-Solver<\/li>\n<\/ul>\n<p><strong>Struktur:<\/strong> Stellen Sie ein klares Ziel dar und geben Sie dann nummerierte Schritte oder Code-Snippets an, die es erreichen.<\/p>\n<h3>3. Technische Referenz (informationsorientiert)<\/h3>\n<p>Die API-Referenzdokumentation beschreibt, was jede Funktion, Klasse und Modul tut. Hier werden umfassende DocStrings kritisch. Die Referenzdokumentation sollte umfassend und pr\u00e4zise sein, sodass erfahrene Benutzer schnell Details nachschlagen k\u00f6nnen.<\/p>\n<h3>4. Erl\u00e4uterung (verst\u00e4ndnisorientiert)<\/h3>\n<p>Erl\u00e4uterungen diskutieren Hintergrund, Designentscheidungen und konzeptionelle Modelle. Sie beantworten &#8222;Warum&#8220; Fragen, die Tutorials und Referenzdokumente nicht k\u00f6nnen. Beispiele:<\/p>\n<ul>\n<li>Warum Finite Volume \u00fcber Finite-Elemente-Methoden w\u00e4hlen?<\/li>\n<li>Die numerische Stabilit\u00e4t im Zeitschritt verstehen<\/li>\n<li>Die Mathematik hinter Phasenfeldmodellen<\/li>\n<\/ul>\n<p>Ein gut strukturiertes Dokumentationsset enth\u00e4lt alle vier Typen, jede an der richtigen Stelle.<\/p>\n<h2>Einrichten Ihres Dokumentationsstapels<\/h2>\n<p>F\u00fcr wissenschaftliche Python-Pakete ist die De-facto-Standard-Toolchain <strong>Sphinx<\/strong> mit <strong>Read the Docs<\/strong>-Hosting.<\/p>\n<h3>Sphinx: Die Dokumentationsmaschine<\/h3>\n<p><a href=\"https:\/\/www.sphinx-doc.org\/\">Sphinx<\/a> ist ein leistungsf\u00e4higer Dokumentationsgenerator, der restrukturierten Text oder Markdown in professionelle Websites, PDFs und E-Books umwandelt. Seine Hauptmerkmale f\u00fcr wissenschaftliche Software:<\/p>\n<ul>\n<li><strong>Automatische API-Dokumentation<\/strong> \u2013 Sphinx kann DocStrings aus Ihrem Python-Code extrahieren und API-Referenzseiten automatisch \u00fcber die Erweiterung <code>autodoc<\/code> generieren.<\/li>\n<li><strong>Querverweise<\/strong> \u2013 Einfache Verkn\u00fcpfung zwischen Dokumentationsseiten und externen Projekten.<\/li>\n<li><strong>Mathematische Notation<\/strong> \u2013 Unterst\u00fctzung f\u00fcr Latex-Gleichungen, die mit MathJAX wiedergegeben werden, die f\u00fcr wissenschaftliche Inhalte unerl\u00e4sslich sind.<\/li>\n<li><strong>Extensible<\/strong> \u2013 Hunderte von Erweiterungen f\u00fcr benutzerdefinierte Funktionen.<\/li>\n<\/ul>\n<p>Zum Einstieg:<\/p>\n<pre><code class=\"language-bash\">pip install sphinx sphinx-rtd-theme\nsphinx-quickstart\n<\/code><\/pre>\n<p>Konfigurieren Sie <code>conf.py<\/code>, um den Pfad Ihres Pakets einzuschlie\u00dfen, und aktivieren Sie Erweiterungen wie <code>sphinx.ext.autodoc<\/code>, <code>sphinx.ext.napoleon<\/code> (f\u00fcr Google\/Numpy DocStrings) und <code>sphinx.ext.mathjax<\/code>.<\/p>\n<h3>Lesen Sie die Dokumente: Kostenloses Hosting mit Automatisierung<\/h3>\n<p><a href=\"https:\/\/readthedocs.org\/\">Read the Docs<\/a> ist eine kostenlose Hosting-Plattform f\u00fcr die Sphinx-Dokumentation. Es l\u00e4sst sich nahtlos in GitHub integrieren:<\/p>\n<ul>\n<li>Verbinden Sie Ihr Repository<\/li>\n<li>Lesen Sie die Dokumente erstellt automatisch eine Dokumentation zu jedem Push<\/li>\n<li>Benutzerdefinierte Domains, Versionsauswahl und PDF-Downloads verf\u00fcgbar<\/li>\n<li>Unterst\u00fctzt mehrere Versionen (stabile, neueste, getaggte Versionen)<\/li>\n<\/ul>\n<p>Diese Automatisierung stellt sicher, dass Ihre Dokumentation immer auf dem neuesten Stand Ihres Codes ist.<\/p>\n<h3>Auswahl eines DocString-Formats: Numpy vs Google<\/h3>\n<p>DocStrings sind die Grundlage der API-Dokumentation. Drei Formate dominieren Python:<\/p>\n<table>\n<thead>\n<tr>\n<th>Format<\/th>\n<th>Eigenschaften<\/th>\n<th>Wissenschaftliche Pr\u00e4ferenz<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><strong> ruhe<\/strong><\/td>\n<td>Original-Sphinx-Format, verwendet <code>:param name: description<\/code> Syntax<\/td>\n<td>Legacy-Projekte<\/td>\n<\/tr>\n<tr>\n<td><strong>Google<\/strong><\/td>\n<td>Sauberes, minimales Markup; Abschnitte mit einfachen Headern<\/td>\n<td>Moderne Projekte, General Python<\/td>\n<\/tr>\n<tr>\n<td><strong>Numpy<\/strong><\/td>\n<td>Strukturierte Abschnitte mit Unterstrichen; Hervorragend f\u00fcr komplexe Signaturen<\/td>\n<td><strong>Wissenschaftliche Python<\/strong><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Der <strong>Numpy-Stil<\/strong> ist in wissenschaftlichen Paketen am h\u00e4ufigsten, da das strukturierte Format mehrere Parameter, Returns und komplexe Typannotationen klar verarbeitet. Der <a href=\"https:\/\/learn.scientific-python.org\/development\/guides\/docs\/\">Scientific Python-Entwicklungshandbuch <\/a> empfiehlt Numpy-Style zu seiner Klarheit.<\/p>\n<p><strong>Beispiel: numpy-string docstring<\/strong><\/p>\n<pre><code class=\"language-python\">def solve_poisson(potential, conductivity, tolerance=1e-6):\n    \"\"\"\n    Solve the Poisson equation \u2207\u00b7(\u03c3\u2207\u03c6) = 0 using finite volumes.\n\n    Parameters\n    ----------\n    potential : ndarray\n        Initial guess for potential field (will be overwritten).\n    conductivity : ndarray\n        Conductivity array on cell centers.\n    tolerance : float, optional\n        Convergence criterion for residual (default: 1e-6).\n\n    Returns\n    -------\n    residual : float\n        Final residual after convergence.\n\n    Notes\n    -----\n    Uses a conjugate gradient solver with Jacobi preconditioner.\n    Boundary conditions must be applied before calling.\n\n    Examples\n    --------\n    &gt;&gt;&gt; phi = np.zeros(grid.shape)\n    &gt;&gt;&gt; sigma = np.ones(grid.shape)\n    &gt;&gt;&gt; residual = solve_poisson(phi, sigma)\n    &gt;&gt;&gt; print(f\"Converged to {residual:.2e}\")\n    \"\"\"\n<\/code><\/pre>\n<p>Die Sphinx-Erweiterung <code>napoleon<\/code> analysiert sowohl Google- als auch Numpy-Stile. W\u00e4hlen Sie sie daher basierend auf den Vorlieben Ihres Teams aus.<\/p>\n<h2>effektive DocStrings schreiben<\/h2>\n<p>Effektive DocStrings folgen konsistenten Konventionen und liefern vollst\u00e4ndige Informationen. <a href=\"https:\/\/www.pyopensci.org\/python-package-guide\/documentation\/write-user-documentation\/document-your-code-api-docstrings.html\">PyOpenSci-Dokumentation Leitfaden <\/a> umrei\u00dft wesentliche Abschnitte:<\/p>\n<h3>Erforderliche Abschnitte<\/h3>\n<ul>\n<li><strong>Summary Line<\/strong> \u2013 Ein Satz beschreibt, was die Funktion bewirkt.<\/li>\n<li><strong>Parameter<\/strong> \u2013 Name, Typ und Beschreibung f\u00fcr jedes Argument.<\/li>\n<li><strong>Returns<\/strong> \u2013 Typ und Beschreibung der R\u00fcckgabewerte.<\/li>\n<li><strong>Erh\u00f6hungen<\/strong> \u2013 Ausnahmen, die ausgel\u00f6st werden k\u00f6nnen.<\/li>\n<\/ul>\n<h3>Optionale, aber wertvolle Abschnitte<\/h3>\n<ul>\n<li><strong>Beispiele<\/strong> \u2013 Snippets f\u00fcr konkrete Nutzung; Diese k\u00f6nnen mit DOCTEST getestet werden.<\/li>\n<li><strong>Notes<\/strong> \u2013 Implementierungsdetails, Algorithmusreferenzen, Leistungsmerkmale.<\/li>\n<li><strong>Referenzen<\/strong> \u2013 Zitate zu Papieren oder externen Dokumentationen.<\/li>\n<li><strong>Siehe auch<\/strong> \u2013 Links zu verwandten Funktionen oder Klassen.<\/li>\n<\/ul>\n<h3>Die Kraft der Beispiele<\/h3>\n<p>Beispiele dienen doppelten Zwecken:<\/p>\n<ol>\n<li>Sie zeigen den Benutzern, wie Sie Ihren Code anwenden k\u00f6nnen.<\/li>\n<li>Sie werden \u00fcber <code>doctest<\/code> ausf\u00fchrbare Tests.<\/li>\n<\/ol>\n<p>Wenn Beispiele als interaktive Python-Sitzungen geschrieben werden, k\u00f6nnen sowohl Benutzer als auch automatisierte Tools \u00fcberpr\u00fcfen, ob sie ordnungsgem\u00e4\u00df funktionieren. Dies sch\u00fctzt vor Dokumentationsf\u00e4ulnis.<\/p>\n<h2>Testdokumentation mit DOCTEST<\/h2>\n<p><a href=\"https:\/\/docs.python.org\/3\/library\/doctest.html\">DocTest<\/a> ist ein Python-Modul, das Codebeispiele in DocStrings \u00fcberpr\u00fcft und die erwartete Ausgabe erzeugt. Dadurch entsteht eine lebendige Dokumentation, die nicht stillschweigend falsch werden kann.<\/p>\n<p><strong>So geht&#8217;s:<\/strong> Sie schreiben ein Beispiel, als ob sie an einer Python-Eingabeaufforderung eingegeben wurden:<\/p>\n<pre><code class=\"language-python\">&gt;&gt;&gt; from mypackage import compute_diffusion\n&gt;&gt;&gt; result = compute_diffusion(concentration=1.0, D=0.01)\n&gt;&gt;&gt; round(result, 4)\n0.1234\n<\/code><\/pre>\n<p>Die Ausf\u00fchrung von <code>pytest --doctest-module<\/code> oder <code>python -m doctest -v your_module.py<\/code> f\u00fchrt diese Beispiele aus und schl\u00e4gt fehl, wenn die Ausgabe abweicht.<\/p>\n<p>F\u00fcr wissenschaftliche Pakete ist DOCTEST besonders wertvoll, weil:<\/p>\n<ul>\n<li>Numerischer Code kann leicht zu falschen Ergebnissen f\u00fchren, ohne Fehler zu verursachen. DocTest f\u00e4ngt stille Ungenauigkeiten auf.<\/li>\n<li>Beispiele zeigen die richtigen Nutzungsmuster (Einheiten, Randbedingungen usw.).<\/li>\n<li>Sie dienen als minimale Regressionstests f\u00fcr die Kernfunktionalit\u00e4t.<\/li>\n<\/ul>\n<p>Das <code>pytest-doctestplus<\/code>-Plugin von Scientific Python bietet erweiterte Funktionen f\u00fcr das Testen der Dokumentation.<\/p>\n<h2>Die Readme: Die Haust\u00fcr Ihres Projekts<\/h2>\n<p>Die Readme ist oft die erste und manchmal nur &#8211; Dokumentierung, auf die Benutzer sto\u00dfen. Eine gut gestaltete Readme sollte an der Wurzel Ihres Repository und auf Pypi erscheinen.<\/p>\n<p><strong>Essential Readme-Abschnitte:<\/strong><\/p>\n<ol>\n<li><strong>Projektbeschreibung<\/strong> \u2013 1-3 S\u00e4tze, die erkl\u00e4ren, was das Paket tut und welche Dom\u00e4ne.<\/li>\n<li><strong>Installationsanweisungen<\/strong> \u2013 So installieren Sie, einschlie\u00dflich Abh\u00e4ngigkeiten und Plattformanforderungen.<\/li>\n<li><strong>Quick-Beispiel<\/strong> \u2013 Minimaler Code-Snippet, der einen typischen Anwendungsfall zeigt.<\/li>\n<li><strong>Links zur vollst\u00e4ndigen Dokumentation<\/strong> \u2013 Direkte Benutzer zu umfassenden Dokumenten, die an anderer Stelle gehostet werden.<\/li>\n<li><strong>Zitatinformationen<\/strong> \u2013 So zitieren Sie die Software in der akademischen Arbeit.<\/li>\n<li><strong>Lizenz<\/strong> \u2013 Geben Sie die Lizenz eindeutig an (z. B. MIT, BSD, GPL).<\/li>\n<li><strong>Badges<\/strong> \u2013 Build-Status, Abdeckung, Pypi-Version usw.<\/li>\n<\/ol>\n<p>Das <a href=\"https:\/\/www.pyopensci.org\/python-package-guide\/documentation\/repository-files\/readme-file-best-practices.html\">pyopensci Readme-Guide<\/a> enth\u00e4lt detaillierte Empfehlungen.<\/p>\n<p><strong>Pro-Tipp:<\/strong> Schreiben Sie Ihre Readme, bevor Sie einen Code schreiben. Dies verdeutlicht die Ziele und das Publikum Ihres Projekts.<\/p>\n<h2>Pflege eines Changelogs<\/h2>\n<p>Ein Changelog ist eine chronologische Liste bemerkenswerter \u00c4nderungen f\u00fcr jede Version. Es antwortet &#8222;Was hat sich zwischen Version X und Y ge\u00e4ndert?&#8220; F\u00fcr Benutzer und Entwickler.<\/p>\n<p><strong>Best Practices:<\/strong><\/p>\n<ul>\n<li>Befolgen Sie <a href=\"https:\/\/keepachangelog.com\/\">Konventionen f\u00fcr Changelog <\/a>.<\/li>\n<li>Verwenden Sie <a href=\"https:\/\/semver.org\/\">Semantische Versionierung <\/a>, um die Kompatibilit\u00e4t zu kommunizieren.<\/li>\n<li>Gruppen\u00e4nderungen nach Typ: <code>Added<\/code>, <code>Changed<\/code>, <code>Deprecated<\/code>, <code>Removed<\/code>, <code>Fixed<\/code>, <code>Security<\/code>.<\/li>\n<li>Schreiben Sie f\u00fcr Menschen: Erkl\u00e4ren Sie, warum eine Ver\u00e4nderung wichtig ist, nicht nur, dass es passiert ist.<\/li>\n<li>Geben Sie Daten f\u00fcr unver\u00f6ffentlichte \u00c4nderungen an.<\/li>\n<li>Automatisieren Sie niemals nur Git Commit-Nachrichten &#8211; kuratieren Sie die Eintr\u00e4ge.<\/li>\n<\/ul>\n<p><strong>Beispielformat:<\/strong><\/p>\n<pre><code class=\"language-markdown\">## [Unreleased]\n### Added\n- New `adaptive_mesh` module for dynamic refinement.\n- Support for HDF5 output with compression.\n\n### Changed\n- `solve()` now returns residual history (breaking change).\n\n### Fixed\n- Memory leak in sparse matrix assembly (#123).\n<\/code><\/pre>\n<p>Ein gutes Changelog schafft Vertrauen, indem es aktive Wartung und Transparenz \u00fcber das Brechen von \u00c4nderungen zeigt.<\/p>\n<h2>H\u00e4ufige Dokumentationsst\u00f6\u00dfe (und wie man sie vermeidet)<\/h2>\n<p>Aufgrund der Literatur und der Community-Erfahrung sind hier h\u00e4ufige Fehler:<\/p>\n<h3>1. Veraltete Dokumentation<\/h3>\n<p>Dokumentation, die dem tats\u00e4chlichen Verhalten widerspricht, ist schlimmer als keine Dokumentation. <strong>L\u00f6sung:<\/strong> Integrieren Sie Dokumentationsaktualisierungen in Code-\u00dcberpr\u00fcfungen. Wenn ein PR die Funktionalit\u00e4t \u00e4ndert, m\u00fcssen die entsprechenden Dokumente im selben Commit aktualisiert werden.<\/p>\n<h3>2. Fehlende Beispiele<\/h3>\n<p>Abstrakte Beschreibungen ohne konkrete Verwendungsbeispiele lassen die Benutzer raten. <strong>L\u00f6sung:<\/strong> Jede \u00f6ffentliche Funktion und Klasse sollte mindestens ein lauff\u00e4higes Beispiel enthalten.<\/p>\n<h3>3. Erkl\u00e4ren &#8222;Was&#8220;, aber nicht &#8222;Warum&#8220;<\/h3>\n<p>Die Dokumentation beschreibt oft die Mechanik, l\u00e4sst aber die Argumentation aus. Benutzer m\u00fcssen den Kontext verstehen, um richtige Entscheidungen zu treffen. <strong>L\u00f6sung:<\/strong> Enth\u00e4lt Abschnitte, in denen erkl\u00e4rt wird, wann eine Funktion verwendet werden soll, Kompromisse und Alternativen.<\/p>\n<h3>4. Nicht\u00fcbereinstimmung des Publikums<\/h3>\n<p>Schreiben f\u00fcr Experten, wenn Anf\u00e4nger das Hauptpublikum sind (oder umgekehrt). <strong>L\u00f6sung:<\/strong> Strukturieren Sie Ihre Dokumente mithilfe des Di\u00e1taxis-Frameworks, um unterschiedliche Bed\u00fcrfnisse separat zu bedienen.<\/p>\n<h3>5. Inkonsistenter Stil<\/h3>\n<p>Gemischte DocString-Formate, unterschiedliche \u00dcberschriftenstufen und Ad-hoc-Organisation. <strong>L\u00f6sung:<\/strong> Nehmen Sie einen Styleguide an und erzwingen Sie ihn mit LINTERS (<code>markdownlint<\/code>, <code>doc8<\/code>).<\/p>\n<h3>6. Keine Pr\u00fcfung<\/h3>\n<p>Ungetestete Beispiele brechen schlie\u00dflich. <strong>L\u00f6sung:<\/strong> Verwenden Sie <code>doctest<\/code> oder <code>pytest-doctestplus<\/code>, um alle Beispiele zu \u00fcberpr\u00fcfen.<\/p>\n<h3>7. Vernachl\u00e4ssigung der Readme<\/h3>\n<p>Angenommen, Benutzer lesen umfangreiche Anleitungen, bevor Sie das Paket ausprobieren. <strong>L\u00f6sung:<\/strong> Machen Sie die Readme \u00fcberzeugend und umsetzbar; F\u00fcgen Sie einen Schnellstartabschnitt hinzu.<\/p>\n<h2>Dokumentation Workflow-Integration<\/h2>\n<p>Die Dokumentation sollte nat\u00fcrlich mit Ihrem Entwicklungsprozess flie\u00dfen:<\/p>\n<h3>Haken vorbefestigen<\/h3>\n<p>Verwenden Sie Pre-Commit-Hooks, um Markdown zu versorgen, und pr\u00fcfen Sie nach h\u00e4ufigen Problemen, bevor Sie Commits zulassen:<\/p>\n<pre><code class=\"language-yaml\"># .pre-commit-config.yaml\nrepos:\n  - repo: https:\/\/github.com\/markdownlint\/markdownlint\n    rev: v0.11.0\n    hooks:\n      - id: markdownlint\n  - repo: https:\/\/github.com\/antonbabenko\/pre-commit-docs\n    rev: v1.6.0\n    hooks:\n      - id: check-links\n<\/code><\/pre>\n<h3>CI\/CD-Pipelines<\/h3>\n<p>Konfigurieren Sie GitHub-Aktionen auf:<\/p>\n<ul>\n<li>Erstellen Sie eine Dokumentation zu jedem Push zum Main<\/li>\n<li>Bereitstellen, um die Dokumente automatisch zu lesen<\/li>\n<li>F\u00fchren Sie <code>doctest<\/code> als Teil der Testsuite aus<\/li>\n<li>Suchen Sie nach defekten Links im erstellten HTML<\/li>\n<\/ul>\n<p>Beispielworkflow:<\/p>\n<pre><code class=\"language-yaml\">name: Documentation\non:\n  push:\n    branches: [main]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions\/checkout@v3\n      - name: Build docs\n        run: |\n          pip install -e .[docs]\n          sphinx-build -b html docs\/ docs\/_build\/html\n<\/code><\/pre>\n<h3>Code-Bewertungen<\/h3>\n<p>Machen Sie die Dokumentation zur \u00dcberpr\u00fcfung einer Checklistenposition:<\/p>\n<ul>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Neue\/ge\u00e4nderte Funktionen haben docStrings<\/li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Beispiele sind enthalten und getestet<\/li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> README wird aktualisiert, wenn benutzerseitige \u00c4nderungen aufgetreten sind<\/li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> \u00c4nderungsprotokolleintrag f\u00fcr Version Bump hinzugef\u00fcgt<\/li>\n<\/ul>\n<h2>Machen Sie Ihre Dokumentation zitierbar<\/h2>\n<p>Wissenschaftliche Software sollte als Forschungsartefakt zitierbar sein. geh\u00f6ren:<\/p>\n<ul>\n<li><strong>Citation.cff<\/strong> \u2013 Eine Standard-Citation.cff-Datei im Repository-Stamm mit Citation-Metadaten (Autoren, Titel, Version, DOI).<\/li>\n<li><strong>Zenodo-Integration<\/strong> \u2013 Verbinden Sie Ihr GitHub-Repository mit Zenodo, um DOIs f\u00fcr jede Version automatisch zuzuweisen.<\/li>\n<li><strong>Anleitung zur Software-Zitierung<\/strong> \u2013 F\u00fcgen Sie Ihrer Readme-Datei einen Abschnitt &#8222;Zitat&#8220; und die Dokumentation zu BibTex-Eintr\u00e4gen hinzu.<\/li>\n<\/ul>\n<p>Dies stellt sicher, dass Ihre Arbeit akademische Kredite erh\u00e4lt und die Anforderungen an die Reproduzierbarkeit von Zeitschriften und F\u00f6rderagenturen erf\u00fcllt.<\/p>\n<h2>Interne Verlinkung und Weiterlesen<\/h2>\n<p>Mehr zu verwandten Themen:<\/p>\n<ul>\n<li><a href=\"\/what-is-scientific-simulation-and-why-it-matters\/\">Verst\u00e4ndnis der wissenschaftlichen Simulation und ihrer Rolle in der Forschung<\/a><\/li>\n<li><a href=\"\/tracking-long-term-technical-debt-in-research-software\/\">Verfolgung langfristiger technischer Schulden in Forschungssoftware<\/a><\/li>\n<li><a href=\"\/managing-research-software-through-tickets\/\">Recherchesoftware \u00fcber Tickets verwalten<\/a><\/li>\n<li><a href=\"\/reproducibility-and-its-role-in-debugging\/\">Reproduzierbarkeit und ihre Rolle beim Debuggen<\/a><\/li>\n<\/ul>\n<p>Diese Artikel behandeln erg\u00e4nzende Aspekte der Entwicklung von Software f\u00fcr nachhaltige Forschung.<\/p>\n<h2>Fazit und n\u00e4chste Schritte<\/h2>\n<p>Die Dokumentation ist keine sekund\u00e4re Aufgabe &#8211; 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\u00e1taxis folgen und die Dokumentation in Ihren Entwicklungsworkflow integrieren, erstellen Sie eine Software, die wirklich wiederverwendbar und reproduzierbar ist.<\/p>\n<p><strong>Heute zu implementierende Aktionselemente:<\/strong><\/p>\n<ol>\n<li>Stellen Sie sicher, dass jede \u00f6ffentliche Funktion und Klasse einen DocString im Numpy- oder Google-Stil hat.<\/li>\n<li>Richten Sie ein <code>docs\/<\/code>-Verzeichnis mit Sphinx-Konfiguration ein.<\/li>\n<li>Verbinden Sie Ihr Repository, um die Dokumente f\u00fcr automatisierte Builds zu lesen.<\/li>\n<li>F\u00fcgen Sie DocTest zu Ihrer CI-Pipeline hinzu, um Beispiele zu \u00fcberpr\u00fcfen.<\/li>\n<li>Schreiben oder verbessern Sie Ihre Readme mit einer klaren Beschreibung und einem schnellen Beispiel.<\/li>\n<li>Starten Sie ein \u00c4nderungsprotokoll, wenn Sie keine haben.<\/li>\n<\/ol>\n<p>Dokumente als Investition behandeln: Die Zeit, die Sie damit verbringen, klare Dokumente zu schreiben, zahlt sich aus, wenn es um die geringere Unterst\u00fctzungslast, die breitere Akzeptanz und die langfristige Wartbarkeit Ihrer wissenschaftlichen Software geht.<\/p>\n<hr>\n<p><strong>Weitere Ressourcen:<\/strong><\/p>\n<ul>\n<li><a href=\"https:\/\/learn.scientific-python.org\/development\/guides\/docs\/\">Wissenschaftlicher Python-Entwicklungsleitfaden: Dokumentation<\/a><\/li>\n<li><a href=\"https:\/\/www.pyopensci.org\/python-package-guide\/documentation\/\">PyOpensci Python-Pakethandbuch: Dokumentation<\/a><\/li>\n<li><a href=\"https:\/\/pmc.ncbi.nlm.nih.gov\/articles\/PMC6301674\/\">Zehn einfache Regeln zur Dokumentation wissenschaftlicher Software<\/a><\/li>\n<li><a href=\"https:\/\/www.sphinx-doc.org\/\">Sphinx-Dokumentation<\/a><\/li>\n<li><a href=\"https:\/\/docs.readthedocs.com\/\">Lesen Sie die Dokumente: Dokumentation f\u00fcr Open-Source-Projekte<\/a><\/li>\n<\/ul>\n","protected":false,"raw":"<p>Hervorragende Dokumentation wandelt wissenschaftliche Python-Pakete vom unbrauchbaren Code in reproduzierbare Forschungsressourcen um. W\u00e4hlen Sie einen <strong>Dokumentation-as-Code<\/strong>-Ansatz: Speichern Sie Dokumente neben dem Code, verwenden Sie <strong>Sphinx<\/strong> mit <strong>Numpy oder Google-Stil-DocStrings<\/strong>, automatisieren Sie Builds mit <strong>Lesen Sie die docs <\/strong> und integrieren Sie Dokumentationsaktualisierungen in jede Code\u00fcberpr\u00fcfung. Schlie\u00dfen Sie eine klare <strong>Readme<\/strong> ein, pflegen Sie ein <strong>Changelog<\/strong> und testen Sie Beispiele mit <strong>DocTest<\/strong>. Behandeln Sie die Dokumentation als erstklassige Leistung, nicht als nachtr\u00e4gliche Idee.<\/p>\n<h2>Warum Dokumentation in wissenschaftlicher Python wichtig ist<\/h2>\n<p>Wissenschaftliche Software erzielt oft keine Wirkung, nicht aufgrund fehlerhafter Algorithmen, sondern weil andere (oder sogar die urspr\u00fcnglichen Autoren Monate sp\u00e4ter) das Werk nicht verstehen oder reproduzieren k\u00f6nnen. Laut einer Studie zu Best Practices f\u00fcr wissenschaftliche Software ist eine klare Dokumentation f\u00fcr Reproduzierbarkeit, Wartbarkeit und Peer-Validierung von wesentlicher Bedeutung. Im Gegensatz zu kommerzieller Software, bei der die Dokumentation h\u00e4ufig vernachl\u00e4ssigt wird, erfordert der Forschungscode eine besonders sorgf\u00e4ltige Dokumentation, um sicherzustellen, dass Rechenergebnisse vertrauensw\u00fcrdig und erweitert werden k\u00f6nnen.<\/p>\n<p>Die Folgen schlechter Dokumentation im wissenschaftlichen Kontext sind:<\/p>\n<ul>\n<li>Unreproduzierbare Ergebnisse aufgrund unklarer Konfiguration<\/li>\n<li>verschwendete Zeit Reverse-Engineering eigener Code Monate sp\u00e4ter<\/li>\n<li>Unf\u00e4higkeit, auf der Arbeit anderer aufzubauen<\/li>\n<li>Fehlgeschlagene Peer-Review der Berechnungsmethoden<\/li>\n<li>Verlassene Projekte, wenn urspr\u00fcngliche Entwickler gehen<\/li>\n<\/ul>\n<p>Eine gute Dokumentation \u00fcberbr\u00fcckt die L\u00fccke zwischen mathematischer Formulierung und Arbeitssimulation - die L\u00fccke, die Matforge geschlossen hat.<\/p>\n<h2>Die Documentation-as-Code-Philosophie<\/h2>\n<p>Der effektivste Dokumentationsansatz in wissenschaftlichen Python-Projekten ist <strong>Dokumentation-as-Code<\/strong> (DAC): Behandeln Sie die Dokumentation mit der gleichen Genauigkeit wie den Quellcode. Das bedeutet:<\/p>\n<ol>\n<li><strong>Versionsdokumentation neben Code<\/strong> \u2013 Speichern Sie Markdown- oder Restrukturierungstextdateien in einem <code>docs\/<\/code>-Verzeichnis im selben Repository wie Ihr Quellcode. Dadurch wird sichergestellt, dass die Dokumentation immer mit der entsprechenden Codeversion \u00fcbereinstimmt.<\/li>\n<li><strong>Dokumentation in Pull Requests<\/strong> \u2013 Machen Sie die Dokumentationsaktualisierungen obligatorisch f\u00fcr Code\u00e4nderungen, die die Funktionalit\u00e4t ver\u00e4ndern. Eine Code-\u00dcberpr\u00fcfung ist unvollst\u00e4ndig, wenn die Dokumentation nicht aktualisiert wird.<\/li>\n<li><strong>Building and Deployment automatisieren<\/strong> \u2013 Verwenden Sie GitHub-Aktionen oder GitLab CI, um bei jedem Push- und Bereitstellungsdienst automatisch Dokumentationen wie Read the Docs zu erstellen.<\/li>\n<li><strong>Wenden Sie die gleichen Qualit\u00e4tsstandards<\/strong> \u2013 Fassen Sie Ihren Markdown, suchen Sie nach defekten Links und behandeln Sie Dokumentationsfehler mit der gleichen Ernsthaftigkeit wie Code-Bugs.<\/li>\n<\/ol>\n<p>Dieser Ansatz verhindert den h\u00e4ufigsten Dokumentationsfehler: Dokumente, die mit dem von ihnen beschriebenen Code nicht synchron sind.<\/p>\n<h2>Das Di\u00e1taxis-Framework: vier Dokumentationstypen<\/h2>\n<p>Eine wirksame Dokumentation dient unterschiedlichen Zwecken. Das Di\u00e1taxis-Framework unterteilt die Dokumentation in vier Kategorien:<\/p>\n<h3>1. Tutorials (lernorientiert)<\/h3>\n<p>Tutorials sind Schritt-f\u00fcr-Schritt-Lektionen, die Neulinge durch eine vollst\u00e4ndige, bedeutungsvolle Aufgabe f\u00fchren. Sie sollten konkret und praxisnah sein und zu einem Arbeitsergebnis f\u00fchren. F\u00fcr wissenschaftliche Python-Pakete k\u00f6nnen Tutorials Folgendes umfassen:<\/p>\n<ul>\n<li>FIPY f\u00fcr ein einfaches Diffusionsproblem einrichten<\/li>\n<li>Ausf\u00fchren Ihrer ersten Phasenfeldsimulation<\/li>\n<li>Validierung eines PDE-Solvers gegen eine analytische L\u00f6sung<\/li>\n<\/ul>\n<p><strong>Schl\u00fcsselprinzip:<\/strong> Tutorials lehren durch Tun. Vermeiden Sie abstrakte Konzepte; Konzentrieren Sie sich auf praktische Schritte mit sofortigem Feedback.<\/p>\n<h3>2. Anleitungen (zielorientiert)<\/h3>\n<p>Anleitungen bieten Rezepte f\u00fcr bestimmte Aufgaben. Im Gegensatz zu Tutorials setzen sie grundlegende Vertrautheit voraus und zielen auf ein klares Ziel. Beispiele:<\/p>\n<ul>\n<li>So implementieren Sie benutzerdefinierte Randbedingungen in FIPY<\/li>\n<li>So parallelisieren Sie Ihre Simulation mit MPI<\/li>\n<li>So profilieren und optimieren Sie einen PDE-Solver<\/li>\n<\/ul>\n<p><strong>Struktur:<\/strong> Stellen Sie ein klares Ziel dar und geben Sie dann nummerierte Schritte oder Code-Snippets an, die es erreichen.<\/p>\n<h3>3. Technische Referenz (informationsorientiert)<\/h3>\n<p>Die API-Referenzdokumentation beschreibt, was jede Funktion, Klasse und Modul tut. Hier werden umfassende DocStrings kritisch. Die Referenzdokumentation sollte umfassend und pr\u00e4zise sein, sodass erfahrene Benutzer schnell Details nachschlagen k\u00f6nnen.<\/p>\n<h3>4. Erl\u00e4uterung (verst\u00e4ndnisorientiert)<\/h3>\n<p>Erl\u00e4uterungen diskutieren Hintergrund, Designentscheidungen und konzeptionelle Modelle. Sie beantworten \"Warum\" Fragen, die Tutorials und Referenzdokumente nicht k\u00f6nnen. Beispiele:<\/p>\n<ul>\n<li>Warum Finite Volume \u00fcber Finite-Elemente-Methoden w\u00e4hlen?<\/li>\n<li>Die numerische Stabilit\u00e4t im Zeitschritt verstehen<\/li>\n<li>Die Mathematik hinter Phasenfeldmodellen<\/li>\n<\/ul>\n<p>Ein gut strukturiertes Dokumentationsset enth\u00e4lt alle vier Typen, jede an der richtigen Stelle.<\/p>\n<h2>Einrichten Ihres Dokumentationsstapels<\/h2>\n<p>F\u00fcr wissenschaftliche Python-Pakete ist die De-facto-Standard-Toolchain <strong>Sphinx<\/strong> mit <strong>Read the Docs<\/strong>-Hosting.<\/p>\n<h3>Sphinx: Die Dokumentationsmaschine<\/h3>\n<p><a href=\"https:\/\/www.sphinx-doc.org\/\">Sphinx<\/a> ist ein leistungsf\u00e4higer Dokumentationsgenerator, der restrukturierten Text oder Markdown in professionelle Websites, PDFs und E-Books umwandelt. Seine Hauptmerkmale f\u00fcr wissenschaftliche Software:<\/p>\n<ul>\n<li><strong>Automatische API-Dokumentation<\/strong> \u2013 Sphinx kann DocStrings aus Ihrem Python-Code extrahieren und API-Referenzseiten automatisch \u00fcber die Erweiterung <code>autodoc<\/code> generieren.<\/li>\n<li><strong>Querverweise<\/strong> \u2013 Einfache Verkn\u00fcpfung zwischen Dokumentationsseiten und externen Projekten.<\/li>\n<li><strong>Mathematische Notation<\/strong> \u2013 Unterst\u00fctzung f\u00fcr Latex-Gleichungen, die mit MathJAX wiedergegeben werden, die f\u00fcr wissenschaftliche Inhalte unerl\u00e4sslich sind.<\/li>\n<li><strong>Extensible<\/strong> \u2013 Hunderte von Erweiterungen f\u00fcr benutzerdefinierte Funktionen.<\/li>\n<\/ul>\n<p>Zum Einstieg:<\/p>\n<pre><code class=\"language-bash\">pip install sphinx sphinx-rtd-theme\nsphinx-quickstart\n<\/code><\/pre>\n<p>Konfigurieren Sie <code>conf.py<\/code>, um den Pfad Ihres Pakets einzuschlie\u00dfen, und aktivieren Sie Erweiterungen wie <code>sphinx.ext.autodoc<\/code>, <code>sphinx.ext.napoleon<\/code> (f\u00fcr Google\/Numpy DocStrings) und <code>sphinx.ext.mathjax<\/code>.<\/p>\n<h3>Lesen Sie die Dokumente: Kostenloses Hosting mit Automatisierung<\/h3>\n<p><a href=\"https:\/\/readthedocs.org\/\">Read the Docs<\/a> ist eine kostenlose Hosting-Plattform f\u00fcr die Sphinx-Dokumentation. Es l\u00e4sst sich nahtlos in GitHub integrieren:<\/p>\n<ul>\n<li>Verbinden Sie Ihr Repository<\/li>\n<li>Lesen Sie die Dokumente erstellt automatisch eine Dokumentation zu jedem Push<\/li>\n<li>Benutzerdefinierte Domains, Versionsauswahl und PDF-Downloads verf\u00fcgbar<\/li>\n<li>Unterst\u00fctzt mehrere Versionen (stabile, neueste, getaggte Versionen)<\/li>\n<\/ul>\n<p>Diese Automatisierung stellt sicher, dass Ihre Dokumentation immer auf dem neuesten Stand Ihres Codes ist.<\/p>\n<h3>Auswahl eines DocString-Formats: Numpy vs Google<\/h3>\n<p>DocStrings sind die Grundlage der API-Dokumentation. Drei Formate dominieren Python:<\/p>\n<table>\n<thead>\n<tr>\n<th>Format<\/th>\n<th>Eigenschaften<\/th>\n<th>Wissenschaftliche Pr\u00e4ferenz<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><strong> ruhe<\/strong><\/td>\n<td>Original-Sphinx-Format, verwendet <code>:param name: description<\/code> Syntax<\/td>\n<td>Legacy-Projekte<\/td>\n<\/tr>\n<tr>\n<td><strong>Google<\/strong><\/td>\n<td>Sauberes, minimales Markup; Abschnitte mit einfachen Headern<\/td>\n<td>Moderne Projekte, General Python<\/td>\n<\/tr>\n<tr>\n<td><strong>Numpy<\/strong><\/td>\n<td>Strukturierte Abschnitte mit Unterstrichen; Hervorragend f\u00fcr komplexe Signaturen<\/td>\n<td><strong>Wissenschaftliche Python<\/strong><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Der <strong>Numpy-Stil<\/strong> ist in wissenschaftlichen Paketen am h\u00e4ufigsten, da das strukturierte Format mehrere Parameter, Returns und komplexe Typannotationen klar verarbeitet. Der <a href=\"https:\/\/learn.scientific-python.org\/development\/guides\/docs\/\">Scientific Python-Entwicklungshandbuch <\/a> empfiehlt Numpy-Style zu seiner Klarheit.<\/p>\n<p><strong>Beispiel: numpy-string docstring<\/strong><\/p>\n<pre><code class=\"language-python\">def solve_poisson(potential, conductivity, tolerance=1e-6):\n    \"\"\"\n    Solve the Poisson equation \u2207\u00b7(\u03c3\u2207\u03c6) = 0 using finite volumes.\n\n    Parameters\n    ----------\n    potential : ndarray\n        Initial guess for potential field (will be overwritten).\n    conductivity : ndarray\n        Conductivity array on cell centers.\n    tolerance : float, optional\n        Convergence criterion for residual (default: 1e-6).\n\n    Returns\n    -------\n    residual : float\n        Final residual after convergence.\n\n    Notes\n    -----\n    Uses a conjugate gradient solver with Jacobi preconditioner.\n    Boundary conditions must be applied before calling.\n\n    Examples\n    --------\n    &gt;&gt;&gt; phi = np.zeros(grid.shape)\n    &gt;&gt;&gt; sigma = np.ones(grid.shape)\n    &gt;&gt;&gt; residual = solve_poisson(phi, sigma)\n    &gt;&gt;&gt; print(f\"Converged to {residual:.2e}\")\n    \"\"\"\n<\/code><\/pre>\n<p>Die Sphinx-Erweiterung <code>napoleon<\/code> analysiert sowohl Google- als auch Numpy-Stile. W\u00e4hlen Sie sie daher basierend auf den Vorlieben Ihres Teams aus.<\/p>\n<h2>effektive DocStrings schreiben<\/h2>\n<p>Effektive DocStrings folgen konsistenten Konventionen und liefern vollst\u00e4ndige Informationen. <a href=\"https:\/\/www.pyopensci.org\/python-package-guide\/documentation\/write-user-documentation\/document-your-code-api-docstrings.html\">PyOpenSci-Dokumentation Leitfaden <\/a> umrei\u00dft wesentliche Abschnitte:<\/p>\n<h3>Erforderliche Abschnitte<\/h3>\n<ul>\n<li><strong>Summary Line<\/strong> \u2013 Ein Satz beschreibt, was die Funktion bewirkt.<\/li>\n<li><strong>Parameter<\/strong> \u2013 Name, Typ und Beschreibung f\u00fcr jedes Argument.<\/li>\n<li><strong>Returns<\/strong> \u2013 Typ und Beschreibung der R\u00fcckgabewerte.<\/li>\n<li><strong>Erh\u00f6hungen<\/strong> \u2013 Ausnahmen, die ausgel\u00f6st werden k\u00f6nnen.<\/li>\n<\/ul>\n<h3>Optionale, aber wertvolle Abschnitte<\/h3>\n<ul>\n<li><strong>Beispiele<\/strong> \u2013 Snippets f\u00fcr konkrete Nutzung; Diese k\u00f6nnen mit DOCTEST getestet werden.<\/li>\n<li><strong>Notes<\/strong> \u2013 Implementierungsdetails, Algorithmusreferenzen, Leistungsmerkmale.<\/li>\n<li><strong>Referenzen<\/strong> \u2013 Zitate zu Papieren oder externen Dokumentationen.<\/li>\n<li><strong>Siehe auch<\/strong> \u2013 Links zu verwandten Funktionen oder Klassen.<\/li>\n<\/ul>\n<h3>Die Kraft der Beispiele<\/h3>\n<p>Beispiele dienen doppelten Zwecken:<\/p>\n<ol>\n<li>Sie zeigen den Benutzern, wie Sie Ihren Code anwenden k\u00f6nnen.<\/li>\n<li>Sie werden \u00fcber <code>doctest<\/code> ausf\u00fchrbare Tests.<\/li>\n<\/ol>\n<p>Wenn Beispiele als interaktive Python-Sitzungen geschrieben werden, k\u00f6nnen sowohl Benutzer als auch automatisierte Tools \u00fcberpr\u00fcfen, ob sie ordnungsgem\u00e4\u00df funktionieren. Dies sch\u00fctzt vor Dokumentationsf\u00e4ulnis.<\/p>\n<h2>Testdokumentation mit DOCTEST<\/h2>\n<p><a href=\"https:\/\/docs.python.org\/3\/library\/doctest.html\">DocTest<\/a> ist ein Python-Modul, das Codebeispiele in DocStrings \u00fcberpr\u00fcft und die erwartete Ausgabe erzeugt. Dadurch entsteht eine lebendige Dokumentation, die nicht stillschweigend falsch werden kann.<\/p>\n<p><strong>So geht's:<\/strong> Sie schreiben ein Beispiel, als ob sie an einer Python-Eingabeaufforderung eingegeben wurden:<\/p>\n<pre><code class=\"language-python\">&gt;&gt;&gt; from mypackage import compute_diffusion\n&gt;&gt;&gt; result = compute_diffusion(concentration=1.0, D=0.01)\n&gt;&gt;&gt; round(result, 4)\n0.1234\n<\/code><\/pre>\n<p>Die Ausf\u00fchrung von <code>pytest --doctest-module<\/code> oder <code>python -m doctest -v your_module.py<\/code> f\u00fchrt diese Beispiele aus und schl\u00e4gt fehl, wenn die Ausgabe abweicht.<\/p>\n<p>F\u00fcr wissenschaftliche Pakete ist DOCTEST besonders wertvoll, weil:<\/p>\n<ul>\n<li>Numerischer Code kann leicht zu falschen Ergebnissen f\u00fchren, ohne Fehler zu verursachen. DocTest f\u00e4ngt stille Ungenauigkeiten auf.<\/li>\n<li>Beispiele zeigen die richtigen Nutzungsmuster (Einheiten, Randbedingungen usw.).<\/li>\n<li>Sie dienen als minimale Regressionstests f\u00fcr die Kernfunktionalit\u00e4t.<\/li>\n<\/ul>\n<p>Das <code>pytest-doctestplus<\/code>-Plugin von Scientific Python bietet erweiterte Funktionen f\u00fcr das Testen der Dokumentation.<\/p>\n<h2>Die Readme: Die Haust\u00fcr Ihres Projekts<\/h2>\n<p>Die Readme ist oft die erste und manchmal nur - Dokumentierung, auf die Benutzer sto\u00dfen. Eine gut gestaltete Readme sollte an der Wurzel Ihres Repository und auf Pypi erscheinen.<\/p>\n<p><strong>Essential Readme-Abschnitte:<\/strong><\/p>\n<ol>\n<li><strong>Projektbeschreibung<\/strong> \u2013 1-3 S\u00e4tze, die erkl\u00e4ren, was das Paket tut und welche Dom\u00e4ne.<\/li>\n<li><strong>Installationsanweisungen<\/strong> \u2013 So installieren Sie, einschlie\u00dflich Abh\u00e4ngigkeiten und Plattformanforderungen.<\/li>\n<li><strong>Quick-Beispiel<\/strong> \u2013 Minimaler Code-Snippet, der einen typischen Anwendungsfall zeigt.<\/li>\n<li><strong>Links zur vollst\u00e4ndigen Dokumentation<\/strong> \u2013 Direkte Benutzer zu umfassenden Dokumenten, die an anderer Stelle gehostet werden.<\/li>\n<li><strong>Zitatinformationen<\/strong> \u2013 So zitieren Sie die Software in der akademischen Arbeit.<\/li>\n<li><strong>Lizenz<\/strong> \u2013 Geben Sie die Lizenz eindeutig an (z. B. MIT, BSD, GPL).<\/li>\n<li><strong>Badges<\/strong> \u2013 Build-Status, Abdeckung, Pypi-Version usw.<\/li>\n<\/ol>\n<p>Das <a href=\"https:\/\/www.pyopensci.org\/python-package-guide\/documentation\/repository-files\/readme-file-best-practices.html\">pyopensci Readme-Guide<\/a> enth\u00e4lt detaillierte Empfehlungen.<\/p>\n<p><strong>Pro-Tipp:<\/strong> Schreiben Sie Ihre Readme, bevor Sie einen Code schreiben. Dies verdeutlicht die Ziele und das Publikum Ihres Projekts.<\/p>\n<h2>Pflege eines Changelogs<\/h2>\n<p>Ein Changelog ist eine chronologische Liste bemerkenswerter \u00c4nderungen f\u00fcr jede Version. Es antwortet \"Was hat sich zwischen Version X und Y ge\u00e4ndert?\" F\u00fcr Benutzer und Entwickler.<\/p>\n<p><strong>Best Practices:<\/strong><\/p>\n<ul>\n<li>Befolgen Sie <a href=\"https:\/\/keepachangelog.com\/\">Konventionen f\u00fcr Changelog <\/a>.<\/li>\n<li>Verwenden Sie <a href=\"https:\/\/semver.org\/\">Semantische Versionierung <\/a>, um die Kompatibilit\u00e4t zu kommunizieren.<\/li>\n<li>Gruppen\u00e4nderungen nach Typ: <code>Added<\/code>, <code>Changed<\/code>, <code>Deprecated<\/code>, <code>Removed<\/code>, <code>Fixed<\/code>, <code>Security<\/code>.<\/li>\n<li>Schreiben Sie f\u00fcr Menschen: Erkl\u00e4ren Sie, warum eine Ver\u00e4nderung wichtig ist, nicht nur, dass es passiert ist.<\/li>\n<li>Geben Sie Daten f\u00fcr unver\u00f6ffentlichte \u00c4nderungen an.<\/li>\n<li>Automatisieren Sie niemals nur Git Commit-Nachrichten - kuratieren Sie die Eintr\u00e4ge.<\/li>\n<\/ul>\n<p><strong>Beispielformat:<\/strong><\/p>\n<pre><code class=\"language-markdown\">## [Unreleased]\n### Added\n- New `adaptive_mesh` module for dynamic refinement.\n- Support for HDF5 output with compression.\n\n### Changed\n- `solve()` now returns residual history (breaking change).\n\n### Fixed\n- Memory leak in sparse matrix assembly (#123).\n<\/code><\/pre>\n<p>Ein gutes Changelog schafft Vertrauen, indem es aktive Wartung und Transparenz \u00fcber das Brechen von \u00c4nderungen zeigt.<\/p>\n<h2>H\u00e4ufige Dokumentationsst\u00f6\u00dfe (und wie man sie vermeidet)<\/h2>\n<p>Aufgrund der Literatur und der Community-Erfahrung sind hier h\u00e4ufige Fehler:<\/p>\n<h3>1. Veraltete Dokumentation<\/h3>\n<p>Dokumentation, die dem tats\u00e4chlichen Verhalten widerspricht, ist schlimmer als keine Dokumentation. <strong>L\u00f6sung:<\/strong> Integrieren Sie Dokumentationsaktualisierungen in Code-\u00dcberpr\u00fcfungen. Wenn ein PR die Funktionalit\u00e4t \u00e4ndert, m\u00fcssen die entsprechenden Dokumente im selben Commit aktualisiert werden.<\/p>\n<h3>2. Fehlende Beispiele<\/h3>\n<p>Abstrakte Beschreibungen ohne konkrete Verwendungsbeispiele lassen die Benutzer raten. <strong>L\u00f6sung:<\/strong> Jede \u00f6ffentliche Funktion und Klasse sollte mindestens ein lauff\u00e4higes Beispiel enthalten.<\/p>\n<h3>3. Erkl\u00e4ren \"Was\", aber nicht \"Warum\"<\/h3>\n<p>Die Dokumentation beschreibt oft die Mechanik, l\u00e4sst aber die Argumentation aus. Benutzer m\u00fcssen den Kontext verstehen, um richtige Entscheidungen zu treffen. <strong>L\u00f6sung:<\/strong> Enth\u00e4lt Abschnitte, in denen erkl\u00e4rt wird, wann eine Funktion verwendet werden soll, Kompromisse und Alternativen.<\/p>\n<h3>4. Nicht\u00fcbereinstimmung des Publikums<\/h3>\n<p>Schreiben f\u00fcr Experten, wenn Anf\u00e4nger das Hauptpublikum sind (oder umgekehrt). <strong>L\u00f6sung:<\/strong> Strukturieren Sie Ihre Dokumente mithilfe des Di\u00e1taxis-Frameworks, um unterschiedliche Bed\u00fcrfnisse separat zu bedienen.<\/p>\n<h3>5. Inkonsistenter Stil<\/h3>\n<p>Gemischte DocString-Formate, unterschiedliche \u00dcberschriftenstufen und Ad-hoc-Organisation. <strong>L\u00f6sung:<\/strong> Nehmen Sie einen Styleguide an und erzwingen Sie ihn mit LINTERS (<code>markdownlint<\/code>, <code>doc8<\/code>).<\/p>\n<h3>6. Keine Pr\u00fcfung<\/h3>\n<p>Ungetestete Beispiele brechen schlie\u00dflich. <strong>L\u00f6sung:<\/strong> Verwenden Sie <code>doctest<\/code> oder <code>pytest-doctestplus<\/code>, um alle Beispiele zu \u00fcberpr\u00fcfen.<\/p>\n<h3>7. Vernachl\u00e4ssigung der Readme<\/h3>\n<p>Angenommen, Benutzer lesen umfangreiche Anleitungen, bevor Sie das Paket ausprobieren. <strong>L\u00f6sung:<\/strong> Machen Sie die Readme \u00fcberzeugend und umsetzbar; F\u00fcgen Sie einen Schnellstartabschnitt hinzu.<\/p>\n<h2>Dokumentation Workflow-Integration<\/h2>\n<p>Die Dokumentation sollte nat\u00fcrlich mit Ihrem Entwicklungsprozess flie\u00dfen:<\/p>\n<h3>Haken vorbefestigen<\/h3>\n<p>Verwenden Sie Pre-Commit-Hooks, um Markdown zu versorgen, und pr\u00fcfen Sie nach h\u00e4ufigen Problemen, bevor Sie Commits zulassen:<\/p>\n<pre><code class=\"language-yaml\"># .pre-commit-config.yaml\nrepos:\n  - repo: https:\/\/github.com\/markdownlint\/markdownlint\n    rev: v0.11.0\n    hooks:\n      - id: markdownlint\n  - repo: https:\/\/github.com\/antonbabenko\/pre-commit-docs\n    rev: v1.6.0\n    hooks:\n      - id: check-links\n<\/code><\/pre>\n<h3>CI\/CD-Pipelines<\/h3>\n<p>Konfigurieren Sie GitHub-Aktionen auf:<\/p>\n<ul>\n<li>Erstellen Sie eine Dokumentation zu jedem Push zum Main<\/li>\n<li>Bereitstellen, um die Dokumente automatisch zu lesen<\/li>\n<li>F\u00fchren Sie <code>doctest<\/code> als Teil der Testsuite aus<\/li>\n<li>Suchen Sie nach defekten Links im erstellten HTML<\/li>\n<\/ul>\n<p>Beispielworkflow:<\/p>\n<pre><code class=\"language-yaml\">name: Documentation\non:\n  push:\n    branches: [main]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions\/checkout@v3\n      - name: Build docs\n        run: |\n          pip install -e .[docs]\n          sphinx-build -b html docs\/ docs\/_build\/html\n<\/code><\/pre>\n<h3>Code-Bewertungen<\/h3>\n<p>Machen Sie die Dokumentation zur \u00dcberpr\u00fcfung einer Checklistenposition:<\/p>\n<ul>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Neue\/ge\u00e4nderte Funktionen haben docStrings<\/li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Beispiele sind enthalten und getestet<\/li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> README wird aktualisiert, wenn benutzerseitige \u00c4nderungen aufgetreten sind<\/li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> \u00c4nderungsprotokolleintrag f\u00fcr Version Bump hinzugef\u00fcgt<\/li>\n<\/ul>\n<h2>Machen Sie Ihre Dokumentation zitierbar<\/h2>\n<p>Wissenschaftliche Software sollte als Forschungsartefakt zitierbar sein. geh\u00f6ren:<\/p>\n<ul>\n<li><strong>Citation.cff<\/strong> \u2013 Eine Standard-Citation.cff-Datei im Repository-Stamm mit Citation-Metadaten (Autoren, Titel, Version, DOI).<\/li>\n<li><strong>Zenodo-Integration<\/strong> \u2013 Verbinden Sie Ihr GitHub-Repository mit Zenodo, um DOIs f\u00fcr jede Version automatisch zuzuweisen.<\/li>\n<li><strong>Anleitung zur Software-Zitierung<\/strong> \u2013 F\u00fcgen Sie Ihrer Readme-Datei einen Abschnitt \"Zitat\" und die Dokumentation zu BibTex-Eintr\u00e4gen hinzu.<\/li>\n<\/ul>\n<p>Dies stellt sicher, dass Ihre Arbeit akademische Kredite erh\u00e4lt und die Anforderungen an die Reproduzierbarkeit von Zeitschriften und F\u00f6rderagenturen erf\u00fcllt.<\/p>\n<h2>Interne Verlinkung und Weiterlesen<\/h2>\n<p>Mehr zu verwandten Themen:<\/p>\n<ul>\n<li><a href=\"\/what-is-scientific-simulation-and-why-it-matters\/\">Verst\u00e4ndnis der wissenschaftlichen Simulation und ihrer Rolle in der Forschung<\/a><\/li>\n<li><a href=\"\/tracking-long-term-technical-debt-in-research-software\/\">Verfolgung langfristiger technischer Schulden in Forschungssoftware<\/a><\/li>\n<li><a href=\"\/managing-research-software-through-tickets\/\">Recherchesoftware \u00fcber Tickets verwalten<\/a><\/li>\n<li><a href=\"\/reproducibility-and-its-role-in-debugging\/\">Reproduzierbarkeit und ihre Rolle beim Debuggen<\/a><\/li>\n<\/ul>\n<p>Diese Artikel behandeln erg\u00e4nzende Aspekte der Entwicklung von Software f\u00fcr nachhaltige Forschung.<\/p>\n<h2>Fazit und n\u00e4chste Schritte<\/h2>\n<p>Die Dokumentation ist keine sekund\u00e4re 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\u00e1taxis folgen und die Dokumentation in Ihren Entwicklungsworkflow integrieren, erstellen Sie eine Software, die wirklich wiederverwendbar und reproduzierbar ist.<\/p>\n<p><strong>Heute zu implementierende Aktionselemente:<\/strong><\/p>\n<ol>\n<li>Stellen Sie sicher, dass jede \u00f6ffentliche Funktion und Klasse einen DocString im Numpy- oder Google-Stil hat.<\/li>\n<li>Richten Sie ein <code>docs\/<\/code>-Verzeichnis mit Sphinx-Konfiguration ein.<\/li>\n<li>Verbinden Sie Ihr Repository, um die Dokumente f\u00fcr automatisierte Builds zu lesen.<\/li>\n<li>F\u00fcgen Sie DocTest zu Ihrer CI-Pipeline hinzu, um Beispiele zu \u00fcberpr\u00fcfen.<\/li>\n<li>Schreiben oder verbessern Sie Ihre Readme mit einer klaren Beschreibung und einem schnellen Beispiel.<\/li>\n<li>Starten Sie ein \u00c4nderungsprotokoll, wenn Sie keine haben.<\/li>\n<\/ol>\n<p>Dokumente als Investition behandeln: Die Zeit, die Sie damit verbringen, klare Dokumente zu schreiben, zahlt sich aus, wenn es um die geringere Unterst\u00fctzungslast, die breitere Akzeptanz und die langfristige Wartbarkeit Ihrer wissenschaftlichen Software geht.<\/p>\n<hr>\n<p><strong>Weitere Ressourcen:<\/strong><\/p>\n<ul>\n<li><a href=\"https:\/\/learn.scientific-python.org\/development\/guides\/docs\/\">Wissenschaftlicher Python-Entwicklungsleitfaden: Dokumentation<\/a><\/li>\n<li><a href=\"https:\/\/www.pyopensci.org\/python-package-guide\/documentation\/\">PyOpensci Python-Pakethandbuch: Dokumentation<\/a><\/li>\n<li><a href=\"https:\/\/pmc.ncbi.nlm.nih.gov\/articles\/PMC6301674\/\">Zehn einfache Regeln zur Dokumentation wissenschaftlicher Software<\/a><\/li>\n<li><a href=\"https:\/\/www.sphinx-doc.org\/\">Sphinx-Dokumentation<\/a><\/li>\n<li><a href=\"https:\/\/docs.readthedocs.com\/\">Lesen Sie die Dokumente: Dokumentation f\u00fcr Open-Source-Projekte<\/a><\/li>\n<\/ul>\n"},"excerpt":{"rendered":"<p><span class=\"span-reading-time rt-reading-time\" style=\"display: block;\"><span class=\"rt-label rt-prefix\">Reading Time: <\/span> <span class=\"rt-time\"> 8<\/span> <span class=\"rt-label rt-postfix\">minutes<\/span><\/span>Hervorragende Dokumentation wandelt wissenschaftliche Python-Pakete vom unbrauchbaren Code in reproduzierbare Forschungsressourcen um. W\u00e4hlen 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\u00fcberpr\u00fcfung. Schlie\u00dfen Sie eine klare Readme ein, pflegen Sie ein Changelog und [&hellip;]<\/p>\n","protected":false,"raw":""},"author":6,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_locale":"de_DE","_original_post":"https:\/\/matforge.org\/?p=220","iawp_total_views":0,"footnotes":""},"categories":[3],"tags":[],"class_list":["post-845","post","type-post","status-publish","format-standard","hentry","category-issue-tracking-tickets-technical-requests","de-DE"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v28.1 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete - matforge.org<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/\" \/>\n<meta property=\"og:locale\" content=\"de_DE\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete - matforge.org\" \/>\n<meta property=\"og:description\" content=\"Reading Time:  8 minutesHervorragende Dokumentation wandelt wissenschaftliche Python-Pakete vom unbrauchbaren Code in reproduzierbare Forschungsressourcen um. W\u00e4hlen 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\u00fcberpr\u00fcfung. Schlie\u00dfen Sie eine klare Readme ein, pflegen Sie ein Changelog und [&hellip;]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/\" \/>\n<meta property=\"og:site_name\" content=\"matforge.org\" \/>\n<meta property=\"article:published_time\" content=\"2026-07-30T12:22:26+00:00\" \/>\n<meta name=\"author\" content=\"steven\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Verfasst von\" \/>\n\t<meta name=\"twitter:data1\" content=\"steven\" \/>\n\t<meta name=\"twitter:label2\" content=\"Gesch\u00e4tzte Lesezeit\" \/>\n\t<meta name=\"twitter:data2\" content=\"12\u00a0Minuten\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/documentation-best-practices-scientific-python-packages\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/documentation-best-practices-scientific-python-packages\\\/\"},\"author\":{\"name\":\"steven\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/8f690fb596d657b12994b83caa788f03\"},\"headline\":\"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete\",\"datePublished\":\"2026-07-30T12:22:26+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/documentation-best-practices-scientific-python-packages\\\/\"},\"wordCount\":2120,\"commentCount\":0,\"articleSection\":[\"Issue Tracking, Tickets & amp; Technische Anfragen\"],\"inLanguage\":\"de\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\\\/\\\/matforge.org\\\/de\\\/documentation-best-practices-scientific-python-packages\\\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/documentation-best-practices-scientific-python-packages\\\/\",\"url\":\"https:\\\/\\\/matforge.org\\\/de\\\/documentation-best-practices-scientific-python-packages\\\/\",\"name\":\"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete - matforge.org\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/#website\"},\"datePublished\":\"2026-07-30T12:22:26+00:00\",\"author\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/8f690fb596d657b12994b83caa788f03\"},\"breadcrumb\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/documentation-best-practices-scientific-python-packages\\\/#breadcrumb\"},\"inLanguage\":\"de\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/matforge.org\\\/de\\\/documentation-best-practices-scientific-python-packages\\\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/matforge.org\\\/de\\\/documentation-best-practices-scientific-python-packages\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/matforge.org\\\/de\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#website\",\"url\":\"https:\\\/\\\/matforge.org\\\/\",\"name\":\"matforge.org\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/matforge.org\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"de\"},{\"@type\":\"Person\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/8f690fb596d657b12994b83caa788f03\",\"name\":\"steven\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"de\",\"@id\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/d46cfcd83a298f27e8d66bfa035514fefca7652f26bd3ef7402f82b68a41ec0f?s=96&d=mm&r=g\",\"url\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/d46cfcd83a298f27e8d66bfa035514fefca7652f26bd3ef7402f82b68a41ec0f?s=96&d=mm&r=g\",\"contentUrl\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/d46cfcd83a298f27e8d66bfa035514fefca7652f26bd3ef7402f82b68a41ec0f?s=96&d=mm&r=g\",\"caption\":\"steven\"},\"url\":\"https:\\\/\\\/matforge.org\\\/author\\\/steven\\\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete - matforge.org","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/","og_locale":"de_DE","og_type":"article","og_title":"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete - matforge.org","og_description":"Reading Time:  8 minutesHervorragende Dokumentation wandelt wissenschaftliche Python-Pakete vom unbrauchbaren Code in reproduzierbare Forschungsressourcen um. W\u00e4hlen 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\u00fcberpr\u00fcfung. Schlie\u00dfen Sie eine klare Readme ein, pflegen Sie ein Changelog und [&hellip;]","og_url":"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/","og_site_name":"matforge.org","article_published_time":"2026-07-30T12:22:26+00:00","author":"steven","twitter_card":"summary_large_image","twitter_misc":{"Verfasst von":"steven","Gesch\u00e4tzte Lesezeit":"12\u00a0Minuten"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/#article","isPartOf":{"@id":"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/"},"author":{"name":"steven","@id":"https:\/\/matforge.org\/#\/schema\/person\/8f690fb596d657b12994b83caa788f03"},"headline":"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete","datePublished":"2026-07-30T12:22:26+00:00","mainEntityOfPage":{"@id":"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/"},"wordCount":2120,"commentCount":0,"articleSection":["Issue Tracking, Tickets & amp; Technische Anfragen"],"inLanguage":"de","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/","url":"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/","name":"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete - matforge.org","isPartOf":{"@id":"https:\/\/matforge.org\/#website"},"datePublished":"2026-07-30T12:22:26+00:00","author":{"@id":"https:\/\/matforge.org\/#\/schema\/person\/8f690fb596d657b12994b83caa788f03"},"breadcrumb":{"@id":"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/#breadcrumb"},"inLanguage":"de","potentialAction":[{"@type":"ReadAction","target":["https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/matforge.org\/de\/documentation-best-practices-scientific-python-packages\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/matforge.org\/de\/"},{"@type":"ListItem","position":2,"name":"Dokumentation Best Practices f\u00fcr wissenschaftliche Python-Pakete"}]},{"@type":"WebSite","@id":"https:\/\/matforge.org\/#website","url":"https:\/\/matforge.org\/","name":"matforge.org","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/matforge.org\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"de"},{"@type":"Person","@id":"https:\/\/matforge.org\/#\/schema\/person\/8f690fb596d657b12994b83caa788f03","name":"steven","image":{"@type":"ImageObject","inLanguage":"de","@id":"https:\/\/secure.gravatar.com\/avatar\/d46cfcd83a298f27e8d66bfa035514fefca7652f26bd3ef7402f82b68a41ec0f?s=96&d=mm&r=g","url":"https:\/\/secure.gravatar.com\/avatar\/d46cfcd83a298f27e8d66bfa035514fefca7652f26bd3ef7402f82b68a41ec0f?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/d46cfcd83a298f27e8d66bfa035514fefca7652f26bd3ef7402f82b68a41ec0f?s=96&d=mm&r=g","caption":"steven"},"url":"https:\/\/matforge.org\/author\/steven\/"}]}},"_links":{"self":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/845","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/users\/6"}],"replies":[{"embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/comments?post=845"}],"version-history":[{"count":1,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/845\/revisions"}],"predecessor-version":[{"id":963,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/845\/revisions\/963"}],"wp:attachment":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/media?parent=845"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/categories?post=845"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/tags?post=845"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}