MkDocs Dokumentation für Carambus¶

Übersicht¶

Das Carambus-Projekt verwendet MkDocs mit dem Material Theme und mkdocs-static-i18n Plugin für eine mehrsprachige, professionelle Dokumentation. Die Dokumentation wird automatisch über GitHub Actions gebaut und als Artifact bereitgestellt.

Architektur¶

📁 Verzeichnisstruktur¶

carambus_api/
├── mkdocs.yml                 # Hauptkonfiguration
├── requirements.txt           # Python-Dependencies
├── docs/                      # Konsolidierte Dokumentation
│   ├── index.md              # Hauptstartseite
│   ├── assets/               # Bilder und Medien
│   ├── changelog/            # Änderungsprotokoll
│   ├── de/                   # Deutsche Dokumentation
│   │   ├── README.md
│   │   ├── DEVELOPER_GUIDE.md
│   │   ├── tournament.md
│   │   └── ...
│   └── en/                   # Englische Dokumentation
│       ├── README.md
│       ├── DEVELOPER_GUIDE.md
│       ├── tournament.md
│       └── ...
├── .github/workflows/
│   └── build-docs.yml        # CI/CD Workflow
└── site/                     # Gebaute Dokumentation (generiert)

🌐 Mehrsprachige Unterstützung¶

Das Projekt verwendet das mkdocs-static-i18n Plugin für vollständige Zweisprachigkeit:

Deutsch (de): Standardsprache, wird zuerst angezeigt
Englisch (en): Zweitsprache, vollständig übersetzt
Sprachumschaltung: Automatisch in der Navigation verfügbar
Separate Navigation: Jede Sprache hat ihre eigene Menüstruktur

Konfiguration¶

🎨 Theme und Design¶

theme:
  name: material
  features:
    - navigation.tabs      # Tab-Navigation
    - search.suggest       # Suchvorschläge
    - header.autohide      # Automatisches Ausblenden der Kopfzeile
  palette:
    - scheme: default
      primary: indigo      # Primärfarbe
    - scheme: slate        # Dark Mode
      primary: indigo

Die Navigation ist für beide Sprachen konfiguriert:

nav:
  - Startseite: index.md
  - Einführung:
      - Über: about.md
      - README: README.md
  - Benutzerhandbuch:
      - Turnierverwaltung: tournament.md
      - Tischreservierung: table_reservation_heating_control.md
      - Scoreboard Setup: scoreboard_autostart_setup.md
      - Modus-Umschaltung: mode_switcher.md
  - Entwicklerhandbuch:
      - Entwicklerhandbuch: DEVELOPER_GUIDE.md
      - Datenbankdesign: database_design.md
      - Datenbanksynchronisation: database_syncing.md
      - Paper Trail Optimierung: paper_trail_optimization.md
  - Admin-Handbuch:
      - Admin-Rollen: admin_roles.md
      - Datenverwaltung: data_management.md
      - Filter-Popup Verwendung: filter_popup_usage.md
  - Referenz:
      - ER-Diagramm: er_diagram.md
      - API: API.md
      - AGB: terms.md
      - Datenschutz: privacy.md

🔌 Plugins¶

plugins:
  - search                    # Volltextsuche
  - i18n:                     # Mehrsprachigkeit
      languages:
        - locale: de
          name: Deutsch
          default: true
          build: true
        - locale: en
          name: English
          build: true
      reconfigure_material: true
      docs_structure: folder

📝 Markdown-Erweiterungen¶

markdown_extensions:
  - pymdownx.highlight        # Syntax-Highlighting
  - pymdownx.superfences      # Code-Blöcke und ER-Diagramme
  - toc:                      # Inhaltsverzeichnis
      permalink: true
  - admonition                # Warnungen und Hinweise
  - attr_list                 # Attribute für Bilder
  - md_in_html                # HTML in Markdown

CI/CD Pipeline¶

🚀 GitHub Actions Workflow¶

name: Build Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Build documentation
        run: mkdocs build

      - name: Upload documentation artifact
        uses: actions/upload-artifact@v4
        with:
          name: documentation-build
          path: ./site
          retention-days: 30

📦 Dependencies¶

mkdocs-material>=9.5.0        # Material Theme
mkdocs-static-i18n>=1.0.0     # Mehrsprachigkeit
pymdown-extensions>=10.0.0    # Markdown-Erweiterungen

Lokale Entwicklung¶

🛠️ Setup¶

# Python-Umgebung aktivieren
cd carambus_api

# Dependencies installieren
pip install -r requirements.txt

# Dokumentation lokal starten
mkdocs serve

# Dokumentation bauen
mkdocs build

🌐 Lokaler Server¶

URL: http://127.0.0.1:8000/carambus-docs/
Live-Reload: Automatische Aktualisierung bei Änderungen
Sprachumschaltung: Verfügbar in der Navigation

📁 Neue Dokumentation hinzufügen¶

Datei erstellen: docs/de/neue_seite.md
Navigation erweitern: In mkdocs.yml hinzufügen
Englische Übersetzung: docs/en/neue_seite.md erstellen
Testen: mkdocs serve ausführen

Features¶

🔍 Suche¶

Volltextsuche in beiden Sprachen
Suchvorschläge während der Eingabe
Sprachspezifische Suchergebnisse

📱 Responsive Design¶

Mobile-optimiert durch Material Theme
Touch-freundlich für Tablets und Smartphones
Dark Mode Unterstützung

🎨 Customization¶

Indigo als Primärfarbe
Carambus-Branding integriert
Professionelles Design

📊 ER-Diagramme¶

Mermaid Integration für ER-Diagramme
Interaktive Diagramme
Responsive Darstellung

Deployment¶

🚀 GitHub Actions¶

Automatischer Build bei jedem Push
Artifact-Upload für Download
30 Tage Retention für Artifacts

📥 Artifact-Download¶

GitHub Actions öffnen: https://github.com/GernotUllrich/carambus/actions
"Build Documentation" Workflow auswählen
"documentation-build" Artifact herunterladen
Entpacken und auf Webserver deployen

🌐 GitHub Pages (Optional)¶

Für automatisches Online-Deployment:

GitHub Pages in Repository-Einstellungen aktivieren
Source: gh-pages Branch oder /docs Ordner
Workflow erweitern um GitHub Pages Deployment

Best Practices¶

📝 Dokumentation schreiben¶

Klare Struktur mit Überschriften
Code-Beispiele mit Syntax-Highlighting
Bilder in docs/assets/ speichern
Links zwischen verwandten Seiten

Relative Links verwenden: [Text](datei.md)
Anker-Links für Abschnitte: [Text](datei.md#abschnitt)
Externe Links mit vollständiger URL

🖼️ Bilder und Medien¶

![Alt-Text](assets/bild.png){width="100%"}
![Alt-Text](assets/bild.png){: .center width="50%"}

⚠️ Warnungen und Hinweise¶

!!! warning "Wichtiger Hinweis"
    Hier steht der wichtige Text.

!!! info "Information"
    Hier steht eine Information.

!!! tip "Tipp"
    Hier steht ein nützlicher Tipp.

Troubleshooting¶

🔧 Häufige Probleme¶

Port bereits belegt¶

# Anderen Port verwenden
mkdocs serve --dev-addr=127.0.0.1:8001

Fehlende Dependencies¶

# Dependencies neu installieren
pip install -r requirements.txt --upgrade

Build-Fehler¶

# Validierung der Konfiguration
mkdocs build --strict

📋 Debugging¶

Logs prüfen: Detaillierte Ausgabe bei Build-Fehlern
Konfiguration validieren: mkdocs build --strict
Dependencies checken: pip list | grep mkdocs

Fazit¶

Die MkDocs-Integration bietet eine professionelle, mehrsprachige Dokumentation mit:

✅ Automatischem CI/CD über GitHub Actions
✅ Vollständiger Zweisprachigkeit (DE/EN)
✅ Responsive Design für alle Geräte
✅ Professionellem Material Theme
✅ Einfacher Wartung und Erweiterung

Die Dokumentation ist ein wichtiger Bestandteil des Carambus-Projekts und wird kontinuierlich gepflegt und erweitert.