Dokumentationsportal betreiben und veröffentlichen

Ziel

Das Dokumentationssystem der aktuellen dbxapp-Installation verbindet zwei Arten von Dokumentation, ohne sie technisch zu vermischen:

1. Redaktionelle Dokumentation in dbxContent Handbücher, Tutorials, Architekturtexte, Betriebsanweisungen, Screenshots und Medien werden mit den normalen dbxapp-Werkzeugen gepflegt. Die maßgebliche deutsche Fassung bleibt die Quelle für Übersetzungen.
2. Generierte Quellcode-Referenz in Doxygen Klassen, Namespaces, Dateien, Methoden und Codebeispiele werden ohne redaktionelle Doppelpflege aus dem versionierten Quellbestand erzeugt.

Das CMS ist das Portal. Doxygen wird als statischer, versionierter Bereich unter reference/current/ eingebunden. Dadurch bleiben Suche, Klassenlinks und Quellreferenzen von Doxygen erhalten. Die Referenz wird über das Modul dbxDocs im Portal eingebettet und kann zusätzlich direkt geöffnet werden.

Alle öffentlichen Dokumentationsseiten liegen kanonisch unter https://doku.dbxapp.de/. Die eigene Dokumentations-Subdomain trennt das umfangreiche Wissensportal sauber von der Produktwebsite. Auf dbxapp.de/dokumentation/ verbleiben ausschließlich permanente 301-Weiterleitungen auf die jeweils entsprechende Seite der Dokumentations-Subdomain.

Verzeichnisstruktur

Redaktionelle Seiten und technische Referenz liegen gemeinsam in der Dokumentationsinstallation. Entwickelt wird weiterhin in der maßgeblichen dbxapp-Quelle; der Referenzlauf liest diesen Quellbestand und aktualisiert ausschließlich doku.dbxapp.de/reference. Produktwebsite und Dokumentationsportal bleiben dadurch klar getrennt.

Design- und Navigationsvertrag

Das Design dbxdocs verwendet:

• das linke, einklappbare Grundlayout des Designs flowers;
• Farben, Komponenten, Formulare, Reports und Fensterdarstellung des blauen dbxapp-Designs;
• eine eigene, sprachabhängige Dokumentationsnavigation;
• vier getrennte Einstiege für Anwender, Administratoren, Entwickler und KI.

Die linke Navigation wird durch diese Modul-Templates bereitgestellt:

• dbxMenu|dbx-docs-main für Deutsch;
• dbxMenu|dbx-docs-main_en für Englisch.

Die CMS-Ordner sind sprachabhängig und bilden echte Untermenüs. Deutsch und Englisch besitzen vollständig verknüpfte Seiten- und Ordnerbäume; lng_uid verbindet jeweils die inhaltlichen Geschwister. Die Standardsprache bleibt Deutsch, Englisch wird unter /en/ mit eigenen kanonischen Permalinks ausgeliefert. Seiten besitzen neben dem vollständigen Titel einen kurzen menu_title.

Doxygen wird aus derselben Produktquelle getrennt in Deutsch und Englisch erzeugt. Die generierten Dateien liegen unter reference/current beziehungsweise reference/en; Quellcode und technische Bezeichner werden dabei nicht verändert.

Designaufruf

Die Basis-URL https://doku.dbxapp.de/ öffnet das Portal direkt im Standarddesign dbxdocs. Das Design gilt einheitlich für Portal, Suche und eingebettete Referenz. Der Link zur dbxapp-Website führt bewusst in die getrennte Produktinstallation; Sitzungen, Benutzer und Content werden nicht zwischen den Domains vorausgesetzt.

Frühere URLs unter dbxapp.de/dokumentation/ werden mit HTTP 301 seitenweise auf denselben Pfad unter doku.dbxapp.de/ geführt. Auch alte flache Dokumentations- und Doxygen-URLs zeigen dauerhaft auf ihr exaktes kanonisches Ziel; eine pauschale Weiterleitung nur auf die Startseite ist nicht zulässig.

Doxygen erzeugen

In der Dokumentationsinstallation:

Doxyfile schreibt nach:

Die Ausgabe wird vollständig aus dem aktuellen Quellbestand reproduziert. Der anschließende Indexlauf integriert Klassen, Methoden, Dateien und Namespaces zusätzlich in die Suche des Moduls dbxDocs.

Die Doxygen-Kopfleiste besitzt für den direkten Aufruf den Link Portal zurück zur dbxContent-Startseite. Innerhalb des Portals blendet dbxDocs doppelte Navigation und Branding aus. Interne Doxygen-Querverweise bleiben im eingebetteten Referenzfenster.

Veröffentlichung

Vor einer Veröffentlichung:

1. Quelltests und Doxygen-Tests ausführen. Anschließend im Modul dbxSelfTest mindestens den Schnelltest, vor einer Veröffentlichung den Kompletttest starten.
2. doxygen Doxyfile ohne Fehler beenden.
3. Portal, mindestens ein Tutorialbild und reference/current/ per HTTP auf Status 200 prüfen.
4. CMS-Untermenüs und die eingebetteten Bereiche Klassen, Namespaces, Dateien und Beispiele prüfen.
5. files/dbxError.log prüfen; eine vorhandene, nicht leere Datei bedeutet Systemstatus Fehler.
6. Erst danach die geprüfte dbxapp-Installation veröffentlichen.

Die Doxygen-Ausgabe ist reproduzierbar und wird nicht manuell bearbeitet. Redaktionelle Änderungen erfolgen ausschließlich in dbxContent. Quellcode-Kommentare werden lokal geändert und beim nächsten Doxygen-Lauf automatisch in die Referenz übernommen.

Gezielt versionierte redaktionelle Seiten werden aus dbx/modules/dbxDocs/content/ provisioniert. Der wiederholbare Abgleich lautet:

Der Lauf aktualisiert nur ausdrücklich revisionierte Seiten, ergänzt fehlende Seiten und invalidiert danach den Content-Cache. Bestehende, nicht markierte CMS-Redaktion wird ohne --force nicht überschrieben.

Mitwirken und Korrekturen beitragen

Hinweise beginnen mit einer konkreten Seite, dem beobachteten Problem und – wenn möglich – einem reproduzierbaren Beispiel. Redaktionelle Korrekturen werden in dbxContent gepflegt; Änderungen an PHP, JavaScript, CSS, DD oder FD entstehen in der dbxapp-Entwicklungsquelle und durchlaufen die zugehörigen Tests.

1. Betroffene URL, Zielgruppe und erwartetes Verhalten festhalten.
2. Änderung an der kanonischen Quelle vornehmen, nicht an Cache- oder Doxygen-Ausgaben.
3. Dokumentations-SelfTest sowie betroffene Produkt-Regressionstests ausführen.
4. Erst den geprüften Stand veröffentlichen und anschließend Sitemap beziehungsweise Referenz neu erzeugen.

So bleiben kleine Hinweise genauso nachvollziehbar wie umfangreiche Beiträge. Der Dokumentations- und System-SelfTest prüft die verbindlichen Abnahmekriterien.

Abnahmekriterien

• linke Navigation sichtbar und per Tastatur bedienbar;
• Navigation kann ein- und ausgeklappt werden;
• blaues dbxapp-Erscheinungsbild ohne flowers-spezifische Gestaltung;
• deutsche und englische CMS-Navigation vollständig lädt;
• alle Tutorialmedien werden über dbxContent ausgeliefert;
• Doxygen unter reference/current/ erreichbar und im Portal eingebettet;
• die Portal-Startseite liegt kanonisch unter /, redaktionelle Unterseiten unter /dokumentation/;
• frühere flache und ehemalige Produktdomain-Dokumentations-URLs liefern exakte 301-Ziele;
• Installations- und SelfTest-Anleitung im Bereich Betrieb & Sicherheit erreichbar;
• Portal-Rücklink in Doxygen funktioniert;
• keine unbearbeiteten Template-Platzhalter;
• keine PHP-Syntaxfehler und kein neuer Eintrag in dbxError.log.