Dokumentation pflegen

Dieser Leitfaden richtet sich an Mitwirkende, die Benutzerseiten, API-Seiten, Beispiele oder die Veröffentlichungspipeline ändern. GitLab Pages veröffentlicht docs/next/source. Der bisherige Baum docs/source bleibt vorübergehend als Rückfallebene der Migration erhalten, ist aber nicht mehr die gepflegte Veröffentlichungsquelle.

Quellstruktur

docs/next/source/de und docs/next/source/en

Zweisprachige Benutzerleitfäden. Beide Bäume besitzen dieselben relativen .rst-Pfade und gleichwertige technische Informationen.

docs/next/source/api

Gemeinsame englische API- und Kommandozeilenreferenz. Kuratierte Seiten zeigen die empfohlenen öffentlichen Schnittstellen; api/full wird generiert.

docs/next/source/_static

Versionskontrollierte Abbildungen und weitere statische Dateien.

docs/next/MIGRATION.md

Prüfstatus der Inhalte aus der veröffentlichten Dokumentation und Checkliste für die Umschaltung.

test/test_docs_next_structure.py

Strukturelle Sicherungen für Sprachparität und wichtige technische Inhalte.

Lokale Einrichtung und Build

Projekt und Dokumentationsabhängigkeiten werden im Repository-Wurzelverzeichnis installiert:

python -m pip install -e ".[docs]"

Graphviz dot ist ein Systemprogramm und kein Python-Paket. Es wird für Graphviz-Direktiven benötigt. Der vollständige Dokumentations-Build behandelt Warnungen als Fehler:

MPLCONFIGDIR=/tmp/mpylab-matplotlib \
sphinx-build -W --keep-going -E -a -b html \
    docs/next/source build/docs

-E -a baut Umgebung und alle Seiten bewusst neu auf, damit kein Cache defekte Referenzen verdeckt. Das Ergebnis beginnt unter build/docs/index.html.

Zusätzlich werden Strukturtests und Whitespace-Prüfung ausgeführt:

python -m pytest test/test_docs_next_structure.py
python tools/check_public_docstrings.py
git diff --check

Zweisprachige Seiten

Jede benutzerorientierte Seite unter einer Sprachwurzel besitzt unter der anderen Wurzel ein Gegenstück mit demselben relativen Pfad. Beide Dateien und beide Toctree-Einträge werden gemeinsam ergänzt. Codenamen, Konfigurationsschlüssel, Einheiten und Kommandobeispiele bleiben identisch; Erläuterungen und UI-Begriffe werden übersetzt.

Python-Docstrings und API-Seiten bleiben ausschließlich englisch. Neue und überarbeitete öffentliche Docstrings verwenden den NumPy-Stil. Es werden keine doppelten deutschen API-Wrapper angelegt. Deutsche Leitfäden verlinken bei Bedarf auf die gemeinsame API.

Navigation, Querverweise und Stichwortverzeichnis

Eine Seite wird nach ihrem hauptsächlichen Zweck eingeordnet: Aufgabe, Messung, Framework, Konfiguration, Ergebnisse oder Hilfe. Sie wird im nächsten Abschnittsindex verlinkt und erhält Querverweise aus verwandten Abläufen. Eine Seite, die nur über mehrere generische Indexseiten erreichbar ist, ist nicht ausreichend auffindbar.

:doc: dient für Seiten, :class:, :func: und :mod: für Python-Objekte sowie :ref: für benannte Ziele und den generierten genindex. Wichtige Fachbegriffe erhalten .. index::-Einträge. Stabile Konzepte werden im zweisprachigen Glossar ergänzt. Dabei ist zu beachten, dass Sphinx-Glossarbegriffe beider Sprachen einen gemeinsamen Namensraum verwenden.

Regeln für die API-Erzeugung

Die kuratierten Seiten unmittelbar unter api/ werden manuell gepflegt. Sie dokumentieren Schnittstellen, die Anwendungen in der Regel verwenden sollen, und wiederholen geerbte Methoden nicht für jeden konkreten Treiber.

Die vollständige Referenz erzeugt sphinx.ext.apidoc entsprechend apidoc_modules in docs/next/source/conf.py. Dateien unter api/full werden nicht manuell geändert; ein sauberer Build kann sie ersetzen. Legacy-Module, generierte Versionsdateien, UI-Implementierungsmodule und andere bewusste Interna werden in conf.py ausgeschlossen. Generierte Seiten verwenden no-index, damit die kuratierte API die primäre indizierte Definition bleibt.

Öffentliche Docstrings werden auf Englisch geschrieben. Eine neue gemeinsame Klasse, Funktion oder Exception gehört in eine kuratierte Seite, wenn sie ein vorgesehener Erweiterungspunkt, häufig in Anwendungen genutzt oder für Lebenszyklus und Sicherheit wichtig ist. Andere öffentliche Module bleiben über die vollständige Referenz auffindbar.

tools/check_public_docstrings.py prüft unabhängig von Sphinx alle importierbaren Module sowie öffentliche Klassen, Funktionen und Methoden unter src/mpylab. Private Namen, Legacy-Module, die generierte Versionsdatei und Framework-Callbacks wie Qt-Slots, PLY-Grammatikregeln und dynamisch ausgewählte Grenzwertkurven sind bewusst ausgenommen. Die Prüfung akzeptiert keine Bestandsliste fehlender Docstrings: eine neue öffentliche Schnittstelle muss direkt einen englischen Docstring erhalten.

Bei Gerätetreibern beschreibt die Basisklasse die gemeinsame Schnittstelle. Ein konkreter Treiber muss geerbte Methoden wie Init, SetFreq oder GetData nicht wortgleich erneut dokumentieren. Der Checker erkennt solche Überschreibungen anhand der tatsächlichen Vererbungskette. Zusätzliche gerätespezifische Methoden, neue Konstruktorparameter sowie fachliche Abweichungen vom Verhalten der Basisklasse benötigen dagegen einen eigenen Docstring. Damit bleibt die Dokumentation konsistent, ohne Kopien des gemeinsamen Geräteverhaltens anzulegen.

Mit --check-signatures vergleicht das Werkzeug zusätzlich die Python- Signatur und tatsächliche Rückgabepfade mit den dokumentierten Parametern, Returns- und Yields-Abschnitten. Während der Umstellung erkennt es auch bestehende reStructuredText- und Google-Abschnitte. Ziel und Vorgabe für neue oder geänderte Schnittstellen ist jedoch der durch sphinx.ext.napoleon dargestellte NumPy-Stil.

python tools/check_public_docstrings.py --check-signatures

Die CI führt diese vollständige Prüfung mit tools/public_docstring_signature_baseline.json aus. Die Baseline hält bekannte Signaturlücken der Bestandsdokumentation komponentengenau fest. Eine neue öffentliche Schnittstelle, ein neuer undokumentierter Parameter oder ein neu fehlender Returns-/Yields-Abschnitt lässt die Prüfung weiterhin fehlschlagen. Verbesserungen sind jederzeit erlaubt und verkleinern die Bestandsabweichung.

python tools/check_public_docstrings.py \
    --signature-baseline tools/public_docstring_signature_baseline.json

Wird eine öffentliche Methode fachlich oder an ihrer Signatur geändert, wird ihr Docstring im selben Arbeitsschritt vollständig geprüft und im NumPy-Stil ergänzt. Die Baseline wird danach nur zum Entfernen der behobenen Altlast aktualisiert. Neue Einträge allein zum Beruhigen der CI sind nicht zulässig.

Abbildungen und generierte Dateien

Gepflegte Diagramme liegen unter docs/next/source/_static und werden relativ zur Seite referenziert. Für Diagramme und Plots ist SVG vorzuziehen, wenn eine Vektorausgabe verfügbar ist. Jede Abbildung benötigt einen aussagekräftigen Alternativtext und eine Bildunterschrift mit ihrer technischen Bedeutung. HTML-Buildverzeichnisse und generierte api/full-Seiten werden nicht eingecheckt, solange der Veröffentlichungsprozess dies nicht bewusst anders festlegt.

Beispiele müssen ausführbar sein oder aus versionskontrollierten virtuellen Konfigurationen stammen. Arbeitsplatzspezifische absolute Pfade, private Messdaten und Hardwarezugangsdaten gehören nicht in die Dokumentation.

Prüfliste

Vor einem Commit wird geprüft:

• Deutsche und englische Seiten haben gleiche Pfade und synchronen Inhalt.

• Kommandos, API-Namen, Konfigurationsschlüssel und Ausgabedateien entsprechen dem Code.

• Neue Seiten stehen in einem Toctree und besitzen nützliche Querverweise.

• Fachbegriffe erhalten bei Bedarf Index- oder Glossareinträge.

• Codebeispiele kennzeichnen notwendigen Hardwarezugriff.

• Bei geänderten öffentlichen Methoden sind Parameter, Rückgabe und Docstring gemeinsam geprüft worden.

• Sphinx läuft mit -W --keep-going -E -a fehlerfrei.

• check_public_docstrings.py, test_docs_next_structure.py und git diff --check laufen durch.

• MIGRATION.md spiegelt abgeschlossene Migrationsarbeit wider.

CI und Veröffentlichung

Der Job create-pages in .gitlab-ci.yml installiert .[docs], prüft die Verfügbarkeit von Graphviz und baut docs/next/source direkt nach public. Warnungen werden dabei als Fehler behandelt. sphinx.ext.apidoc erzeugt api/full während dieses Builds entsprechend der conf.py. Die bisherigen Hilfsskripte tools/docs_generate_api.py und tools/docs_audit.py gehören zum alten Veröffentlichungspfad und werden für die aktuelle Dokumentation nicht ausgeführt.

Der Job test führt zuvor tools/check_public_docstrings.py mit der versionierten Signatur-Baseline aus. Damit blockieren eine neue undokumentierte öffentliche Python-Schnittstelle und jede neue oder verschlechterte Signaturlücke bereits die Teststufe und nicht erst die Sphinx-Veröffentlichung.

Für alte Dokumentations-URLs werden keine Kompatibilitäts-Redirects erzeugt. Die neue Informationsarchitektur ist maßgeblich. docs/source bleibt einen Release-Zyklus unverändert als Rückfallebene erhalten und kann danach in einem getrennt geprüften Commit entfernt werden.

Historische Inhalte

Historische Leitfäden bleiben wertvoll, dürfen aber nicht wie aktuelle Betriebsanweisungen erscheinen. Sie liegen in passenden de/archive- und en/archive-Seiten mit deutlichen historischen Hinweisen und Verweisen auf aktuelle Ersatzseiten. Ein historisches Verfahren wird nicht still modernisiert; Korrekturen gehören in den aktuellen Leitfaden.

Den abgeschlossenen Migrationsstand und die Entscheidung zu alten URLs hält die Datei docs/next/MIGRATION.md außerhalb des Sphinx-Quellbaums.