Zum Inhalt

Dokumentations-Build und Deployment

1. Quellstruktur

Englisch ist Standardsprache der Website; Deutsch spiegelt jede Seite auf demselben relativen Pfad.

docs/
  en/...
  en/assets/screenshots/...
  de/...
  de/assets/screenshots/...
  assets/screenshot-manifest.json

README.md ist Englisch, README_DE.md Deutsch. Markdown/MkDocs ist verbindliche Quelle. Generiertes site/ wird nicht manuell bearbeitet.

2. Lokale Vorschau

python -m venv .venv-docs
.\.venv-docs\Scripts\Activate.ps1
pip install -r docs-requirements.txt
python scripts/verify_documentation.py
mkdocs serve

Englisch liegt unter /, Deutsch unter /de/. Der Material-Sprachumschalter bleibt auf der gleichen relativen Seite.

3. Strikter Build

mkdocs build --strict --clean

mkdocs-static-i18n nutzt Ordnerstruktur ohne Fallback; ein fehlendes deutsches Gegenstück zeigt daher nicht still Englisch. mkdocs-redirects erhält frühere flache deutsche Dokumentations-URLs.

4. Screenshots erzeugen

.\venv\Scripts\python.exe scripts\capture_documentation_screenshots.py

Das Werkzeug verwendet isolierte temporäre Konfiguration/Datenbank, deaktiviert externe Dienste und schreibt stabile semantische PNG-Namen für en-GB/de-DE. Niemals auf state/archive.db oder produktive Cloud-/Quellenzugänge zeigen.

Das Manifest protokolliert Locale, Programmpunkt, Datei und Profil. Visuell sind das Branding von FLEET Mira, nicht abgeschnittene Inhalte und das Fehlen personenbezogener Daten, produktiver Endpunkte und Zugangsdaten zu prüfen.

5. Prüfskript

scripts/verify_documentation.py prüft:

  • exakte Pfadparität DE/EN;
  • vorhandene referenzierte Bilder;
  • gültige Screenshotmanifestdateien;
  • keine Windows-Benutzerpfade/typischen Secretmuster;
  • keine unerlaubte sichtbare Legacy-Produktbezeichnung;
  • README-Sprachlinks und Pflichtseiten.

Das Skript ist Leitplanke, ersetzt keine inhaltliche/visuelle Prüfung.

6. CI-Publikation

.github/workflows/publish-docs.yml installiert Dokumentationsabhängigkeiten, führt Verifikation und mkdocs build --strict --clean aus, checkt das öffentliche technische Dokumentationsrepository aus und ersetzt dessen generierte Inhalte.

DOCS_DEPLOY_TOKEN benötigt nur Schreibrecht am Zielrepository. Pull Requests sollen bauen, aber ohne vertrauenswürdigen Tokenkontext nicht veröffentlichen.

Der Zielrepositoryname darf aus Kompatibilität die technische Altkennung DTCONGDownloadTool-docs behalten; Seitentitel/Inhalt heißen FLEET Mira.

7. Autorenregeln

  • Englisch/Deutsch in derselben Änderung aktualisieren.
  • Identische relative Seiten-/Bildpfade je Sprache.
  • Nur implementiertes Verhalten beschreiben.
  • Stabile IDs/Status/API-Felder in Codeformat unverändert.
  • Sichtbar FLEET Mira; DLTNG nur in erklärten Legacy-Kompatibilitätsstellen.
  • Mermaidbeschriftung, Captions und Alttexte lokalisieren.
  • Keine produktiven DDD, DB, Belege, Logs, Tokens, Servernamen oder Benutzerpfade committen.
  • Nach sichtbarer UI-/Navigationsänderung Screenshots neu erzeugen.

8. Releasecheckliste

  • [ ] Dokumentationsprüfung erfolgreich;
  • [ ] strikter MkDocs-Build erfolgreich;
  • [ ] Sprachumschalter öffnet Gegenstück;
  • [ ] alte flache URLs leiten weiter;
  • [ ] Screenshots in beiden Locales;
  • [ ] README/Navigation passen zum Release;
  • [ ] APIs/Datenverträge passen zu Code/Version;
  • [ ] keine Secrets/Betriebsdaten im Build.