.. _doku-architektur:

####################################
Architektur der Dokumentation
####################################

Überblick
=========

Die Dokumentation der Feuerwehr Aidlingen basiert auf bewährten
Open-Source-Technologien und folgt modernen Standards für technische
Dokumentation.

.. important::

   **Keine Sorge!** Als Autor müssen Sie die technischen Details nicht
   kennen. Dieser Abschnitt erklärt, wie das System im Hintergrund
   funktioniert.


Technologie-Stack
=================

**Sphinx**
   Dokumentationsgenerator - erstellt aus Textdateien eine moderne Website

**Furo Theme**
   Modernes, responsives Design für optimale Lesbarkeit

**Python**
   Programmiersprache für Build-Prozess und Erweiterungen

**Git / GitLab**
   Versionskontrolle und Zusammenarbeit


System-Architektur (vereinfacht)
=================================

.. uml::

   @startuml
   skinparam monochrome true
   skinparam shadowing false
   skinparam backgroundColor white
   skinparam defaultFontSize 11

   rectangle "Autoren" {
      component "Feuerwehrmann/-frau" as Author
   }

   rectangle "Quelldateien" {
      component "RST/Markdown" as Source
      component "Bilder & PDFs" as Assets
   }

   rectangle "Build-System" {
      component "Sphinx" as Sphinx
   }

   rectangle "Ausgabe" {
      component "HTML Website" as HTML
   }

   rectangle "Bereitstellung" {
      component "Web Server" as Web
   }

   Author --> Source : schreibt
   Source --> Sphinx : wird verarbeitet
   Assets --> Sphinx : eingebunden
   Sphinx --> HTML : generiert
   HTML --> Web : veröffentlicht
   Web --> Author : nutzt

   @enduml

Die Dokumentation durchläuft mehrere Schritte:

1. **Erstellung**: Autoren schreiben Inhalte in einfachen Textdateien
2. **Verarbeitung**: Sphinx wandelt die Textdateien in HTML um
3. **Veröffentlichung**: Die fertige Website wird auf einem Server bereitgestellt


Dateiformat und Struktur
=========================

Unterstützte Formate
--------------------

.. list-table::
   :header-rows: 1
   :widths: 20 40 40

   * - Format
     - Verwendung
     - Vorteil
   * - **RST** (reStructuredText)
     - Technische Dokumentation, komplexe Layouts
     - Sehr mächtig, viele Features
   * - **Markdown**
     - Einfache Texte, Listen, Tabellen
     - Einfach zu lernen, weit verbreitet
   * - **PDF/Bilder**
     - Bestehende Dokumente, Grafiken
     - Kann direkt eingebunden werden


Verzeichnisstruktur
-------------------

Die Dokumentation ist logisch in Hauptbereiche gegliedert:

.. code-block:: text

   ffw_doc/
   ├── 00-doku-konzept/      # Dieses Kapitel
   ├── 01-organisation/      # Struktur, Gerätehaus, Onboarding
   ├── 02-regelwerke/        # Vorschriften, AAO
   ├── 03-wissen/            # Ausbildung, Digitalfunk
   ├── 04-einsatzmittel/     # Fahrzeuge, Geräte
   ├── _static/              # Bilder, PDFs, CSS
   │   ├── images/
   │   └── pdf/
   └── _templates/           # Vorlagen für neue Seiten

.. tip::

   Die Nummerierung (00, 01, 02...) bestimmt die Reihenfolge im Hauptmenü.


Komponenten-Architektur
========================

.. uml::

   @startuml
   skinparam monochrome true
   skinparam shadowing false
   skinparam backgroundColor white
   skinparam defaultFontSize 11

   component "conf.py" as Config
   component "index.rst" as Index

   package "Kapitel" {
      component "01-organisation" as Org
      component "02-regelwerke" as Rules
      component "03-wissen" as Know
      component "04-einsatzmittel" as Equip
   }

   package "Assets" {
      component "_static/images" as Images
      component "_static/pdf" as PDFs
   }

   package "Templates" {
      component "fahrzeug_template" as VehTemplate
      component "sop_template" as SOPTemplate
   }

   Config --> Index
   Index --> Org
   Index --> Rules
   Index --> Know
   Index --> Equip

   Org ..> Images
   Org ..> PDFs
   Rules ..> PDFs

   VehTemplate ..> Equip
   SOPTemplate ..> Rules

   @enduml


Organisation der Inhalte
=========================

Jedes Hauptkapitel folgt demselben Muster
------------------------------------------

.. code-block:: text

   kapitel-name/
   ├── index.rst              # Übersichtsseite des Kapitels
   ├── unterkapitel-1.rst     # Einzelne Seiten
   ├── unterkapitel-2.rst
   └── bilder/                # Kapitel-spezifische Bilder (optional)


Verlinkung zwischen Seiten
---------------------------

Seiten können miteinander verlinkt werden:

.. code-block:: rst

   # Verweis auf eine andere Seite
   Siehe :doc:`../01-organisation/onboarding/neuaufnahme`

   # Verweis auf einen Abschnitt
   Siehe :ref:`doku-konzept-why`


Build-Prozess
=============

Lokale Entwicklung
------------------

Für Redakteure, die lokal arbeiten:

.. code-block:: bash

   # Voraussetzungen installieren
   poetry install

   # Dokumentation bauen
   poetry run sphinx-build -b html . build/

   # Live-Vorschau mit automatischem Reload
   poetry run sphinx-autobuild . build/

.. note::

   Die meisten Autoren müssen dies nicht selbst ausführen - sie können
   Änderungen einfach als Merge Request einreichen.


Automatische Builds (CI/CD)
----------------------------

.. uml::

   @startuml
   skinparam monochrome true
   skinparam shadowing false
   skinparam backgroundColor white
   skinparam defaultFontSize 11

   start
   :Autor committed Änderung;
   :GitLab CI/CD startet;
   :Rechtschreibprüfung;
   :Link-Validierung;
   :Sphinx Build;
   if (Alles erfolgreich?) then (ja)
      :Website aktualisieren;
      stop
   else (nein)
      :Fehler melden;
      stop
   endif
   @enduml

Bei jeder Änderung:

1. Automatische Prüfung der Rechtschreibung
2. Validierung aller Links
3. Bauen der HTML-Ausgabe
4. Bei Erfolg: Automatische Veröffentlichung


Qualitätssicherung
==================

Automatische Checks
-------------------

- **Rechtschreibprüfung**: Erkennt Tippfehler
- **Link-Validierung**: Prüft ob alle Verweise funktionieren
- **Syntax-Prüfung**: Stellt sicher, dass die Dateien korrekt formatiert sind
- **Bild-Validierung**: Prüft, ob alle referenzierten Bilder existieren


Erweiterbarkeit
===============

Die Architektur ist erweiterbar für zukünftige Anforderungen:

- **Erweiterte Suche**: Integration von Suchmaschinenoptimierung
- **Mobile App**: Native Apps für iOS/Android möglich
- **Zugriffskontrolle**: Geschützte Bereiche für interne Infos
- **Mehrsprachigkeit**: Übersetzungen in andere Sprachen
- **Analytics**: Nutzungsstatistiken und Zugriffsanalysen
- **API-Integration**: Anbindung an andere Systeme


Performance & Verfügbarkeit
============================

**Schnelle Ladezeiten**
   Statische HTML-Seiten laden sehr schnell

**Offline-Fähigkeit**
   Browser können Seiten für Offline-Nutzung cachen

**Skalierbarkeit**
   Beliebig viele Seiten und Nutzer möglich

**Backup & Versionierung**
   Alle Änderungen sind in Git gesichert und wiederherstellbar


Technische Abhängigkeiten
==========================

.. list-table::
   :header-rows: 1
   :widths: 25 35 40

   * - Komponente
     - Version
     - Zweck
   * - Python
     - 3.10+
     - Build-System
   * - Sphinx
     - 8.0+
     - Dokumentationsgenerator
   * - Furo
     - aktuell
     - Theme/Design
   * - MyST Parser
     - aktuell
     - Markdown-Unterstützung
   * - Sphinx-Design
     - aktuell
     - UI-Komponenten (Karten, Grids)
   * - PlantUML
     - aktuell
     - Diagramme
   * - sphinxcontrib-spelling
     - aktuell
     - Rechtschreibprüfung

.. seealso::

   Die vollständige Liste der Abhängigkeiten finden Sie in der Datei
   `pyproject.toml` im Projekt-Root.