ET-DOC-PUBLISHER-001

Documentation Publisher Contract#

Eingaben#

Ein Publisher erhält eine explizite Quellenwurzel, eine freigegebene Einstiegsliste, Ausgabeparameter und optional eine Vorlage. Implizite globale Suchpfade sind nicht zulässig.

Ausgaben#

deterministische Veröffentlichungsartefakte,
Quellen-zu-Ausgabe-Zuordnung,
Liste ausgelassener oder fehlerhafter Quellen,
Validierungs- und Versionsinformationen.

Verhalten#

Dry-Run oder Planmodus muss ohne Quelländerung möglich sein.
Gleiche Eingaben und gleiche Werkzeugversion erzeugen semantisch gleiche Ausgaben.
Unbekannte zulässige Frontmatter-Felder bleiben erhalten oder werden nachweisbar durchgereicht.
Fehlerhafte Referenzen werden nicht stillschweigend entfernt.
Sichtbare Linktexte folgen dem DISPLAY_TITLE_CONTRACT.md: Ein deutscher

Anzeige-Titel hat Vorrang; ein deklarierter deutscher H1 ist der einzige kontrollierte Fallback.

Generierte Ausgaben werden außerhalb der führenden Dokumentationsquellen abgelegt.

Präsentationsdimensionen#

Falls ein Dokument presentation_dimension besitzt, rendert der Publisher ein dezentes, zugängliches Badge mit sichtbarem Textlabel, Icon und Tooltip. Die zulässigen Werte sind , , , context-time, structure, control und report. Fehlende oder unbekannte Werte erzeugen kein erfundenes Badge. artifact_type bleibt davon unabhängig und unverändert.

Standard-Reportdarstellung#

Die führende Darstellung für veröffentlichte Dokumentationsreports liegt in ns_report_publisher/themes/default/report.css. Die Standardpalette ist für Desktop und Mobilgeräte identisch und wird nicht vom Systemmerkmal prefers-color-scheme überschrieben. Die mobilen Breakpoints bei 800 px und 600 px dürfen nur Anordnung und Interaktion anpassen: bei 800 px die Navigation und Seitenanordnung, bei 600 px die Hover- und Kartenbedienung. Damit bleibt ein Report beim Wechsel zwischen Desktop und Mobilgerät fachlich und visuell derselbe Report.

Wissensinteraktion#

Für eindeutig aufgelöste Artifact-Identitäten rendert der Publisher eine Kurzvorschau mit Klickvertiefung für meaning, artifact, relationship und context-time. Sie enthält , Titel, technischen Typ, Summary und einen Link zur kanonischen Reportseite. Bestehende sichere Code-Referenzen erhalten dieselbe Bedienform mit Link zur auswählbaren Codeansicht.

Freie Worttreffer, ähnliche Dateinamen und unqualifizierte Codewörter lösen keine Interaktion aus. structure, control und report bleiben in diesem Schritt auf das Seitenbadge beschränkt.

Deployment-Sicht#

Ein Dokument mit deployment_view: true kann eine strukturelle Deployment-Sicht aus kanonischen Wissenselementen erzeugen. Elemente mit deployment_stereotype: compute-node oder external-work-environment werden als Betriebsknoten (große Container) dargestellt. component und runtime-target werden über deployment_node innerhalb des jeweiligen Containers angeordnet. Der Publisher erfindet keine Infrastrukturwerte: stabile, explizit deklarierte deployment_parameters und die unter ## Externe Evidenz hinterlegten, sichtbaren externen Links werden nur projiziert. Hover zeigt die Kurzfassung; Klick führt zur zentralen Artifact-Dokumentation.

Building-Block-Sicht#

Ein Dokument mit building_block_view: true und building_block_focus erzeugt eine Level-1-Sicht. Artifacts mit building_block_boundary_for erscheinen außerhalb der fokussierten Component; Artifacts mit building_block_parent liegen als Cards innerhalb ihrer großen Kiste. Diese Sicht projiziert nur explizit deklarierte Artifacts und Source-Referenzen. Sie ergänzt die Deployment-Sicht; sie ersetzt keine Prozess-, Activity- oder Sequence-Sicht.

Abgeleitete Sicht-Rückverweise#

Der fokussierte Knoten eines Kontextzeichenbretts ist selektierbar. Sein Klickpanel zeigt den Rückverweisbereich, wenn das Artifact in einer explizit deklarierten Deployment- oder Building-Block-Sicht erscheint. Der Publisher wertet ausschließlich deployment_view, deployment_stereotype, building_block_view, building_block_parent und building_block_boundary_for aus. Der Rückverweis nennt Sicht, strukturelle Rolle und einen direkten Link zur Sicht; er wird nicht zusätzlich weit unten an den Dokumentkörper angehängt.

README.md, Navigations- und Sichtdokumente sowie normale Markdown-Links erzeugen keinen Rückverweis. Die Strukturverwendung wird abgeleitet; die fachliche Artifact-Beschreibung bleibt an ihrer kanonischen Stelle.

Verschachtelte Linktexte#

Ein Markdown-Link mit Inline-Code als sichtbarem Text bleibt ein lesbarer Link. Interne Renderer-Platzhalter dürfen niemals in HTML-Ausgaben erscheinen. Der Inline-Code- und Codeblock-Schutz bleibt dabei unverändert wirksam.

Veröffentlichung#

Eine Veröffentlichung ist erst erfolgreich, wenn Rendering, Referenzauflösung und die Linkprüfung erfolgreich sind. Der Publisher-Aufrufer übergibt die freigegebenen Repository-Roots und die erzeugte HTML-Datei an ; ein FAILED-Befund blockiert den Build und wird als JSON- und Markdown-Korrekturreport bewahrt. Teilresultate müssen als unvollständig gekennzeichnet werden.

Code-Referenzen#

Jede sichtbare Code-Referenz erhält eine sichere Artefakt-ID und einen Link auf eine eigene HTML-Codeansicht. Diese zeigt Repositorypfad, Sprache, Revision/, auswählbaren Inhalt und Rückverweis. Zulässig sind nur .py, .go, .js, .ts, .json und .sh bis 100 KiB. Absolute oder aufsteigende Pfade sowie als sensibel markierte Pfade werden nicht publiziert.