.. index:: Dokumentationspflege, Sphinx-Build, Dokumentationsveröffentlichung 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: .. code-block:: console 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: .. code-block:: console 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: .. code-block:: console 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. .. code-block:: console 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. .. code-block:: console 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.