# Konzept: Automatische Dokumentationserstellung für modulare Python-Pakete

## 1. Überblick

Dieses Konzept beschreibt die automatische Erstellung und Zusammenführung von Dokumentationen für mehrere Python-Pakete (questra-data, questra-authentication, etc.) in eine einheitliche Gesamtdokumentation.

## 2. Anforderungen

### 2.1 Funktionale Anforderungen
- Automatische Generierung von API-Dokumentation aus Docstrings
- Manuelle Dokumentation (Tutorials, Guides, Konzepte)
- Versionierung der Dokumentation pro Paket
- Zentrale Gesamtdokumentation über alle Pakete
- Suchfunktion über alle Dokumentationen
- Code-Beispiele mit Syntax-Highlighting
- Automatische Updates bei Code-Änderungen

### 2.2 Nicht-funktionale Anforderungen
- Minimaler manueller Wartungsaufwand
- Konsistentes Look & Feel
- Schnelle Build-Zeiten
- SEO-freundlich (falls öffentlich)
- Responsive Design für Mobile

## 3. Tool-Auswahl: MkDocs vs. Sphinx

### 3.1 Vergleich

| Kriterium | MkDocs | Sphinx |
|-----------|--------|--------|
| **Konfiguration** | Einfach (YAML) | Komplex (Python) |
| **Markdown-Support** | Native | Via Extension |
| **API-Dokumentation** | Via mkdocstrings | Native (autodoc) |
| **Themes** | Material Theme (Modern) | Read the Docs (Klassisch) |
| **Lernkurve** | Flach | Steil |
| **Python-Integration** | Gut | Exzellent |
| **Multi-Projekt** | Via Monorepo Plugin | Via intersphinx |
| **Performance** | Schnell | Langsamer |

### 3.2 Empfehlung: **MkDocs mit Material Theme**

**Begründung:**
1. **Einfachheit**: Deutlich einfachere Konfiguration und Wartung
2. **Modernes Design**: Material Theme bietet ein zeitgemäßes, professionelles Design
3. **Markdown-First**: Passt besser zu moderner Dokumentationspraxis
4. **mkdocstrings**: Hervorragende Python API-Dokumentation aus Docstrings
5. **monorepo-Plugin**: Speziell für Multi-Paket-Szenarien entwickelt
6. **Community**: Aktive Entwicklung und große Community

**Sphinx wäre besser wenn:**
- Komplexe mathematische Formeln benötigt werden
- Extensive Cross-Referencing zwischen vielen Dokumenten nötig ist
- Das Team bereits Sphinx-Expertise hat

## 4. Architektur-Konzept

### 4.1 Repository-Struktur

#### Option A: Monorepo (Empfohlen für aktuellen Stand)
```
S2O.PoC.Questra.Python.Packages/
├── questra-data/
│   ├── src/
│   ├── docs/
│   │   ├── index.md
│   │   ├── api/
│   │   ├── tutorials/
│   │   └── guides/
│   ├── mkdocs.yml
│   └── pyproject.toml
├── questra-authentication/
│   ├── src/
│   ├── docs/
│   │   ├── index.md
│   │   ├── api/
│   │   └── guides/
│   ├── mkdocs.yml
│   └── pyproject.toml
├── docs/                      # Zentrale Dokumentation
│   ├── index.md
│   ├── getting-started.md
│   └── architecture.md
├── mkdocs.yml                 # Haupt-Konfiguration
└── .github/
    └── workflows/
        └── docs.yml           # CI/CD für Dokumentation
```

#### Option B: Separate Repositories (Für zukünftige Skalierung)
```
Jedes Paket in eigenem Repository:
questra-data/
├── src/
├── docs/
├── mkdocs.yml
└── .github/workflows/docs.yml

Zentrale Dokumentation in separatem Repository:
questra-docs/
├── docs/
├── mkdocs.yml
├── scripts/
│   └── fetch-package-docs.py
└── .github/workflows/
    └── build-combined.yml
```

### 4.2 Empfohlene Architektur: **Hybrid-Ansatz**

**Phase 1 (Jetzt)**: Monorepo mit mkdocs-monorepo-plugin
**Phase 2 (Später)**: Migration zu separaten Repositories mit zentralem Docs-Repo

## 5. Technische Implementierung

### 5.1 Technologie-Stack

```toml
# pyproject.toml - Dev Dependencies für Dokumentation
[dependency-groups]
docs = [
    "mkdocs>=1.5.3",
    "mkdocs-material>=9.5.0",
    "mkdocstrings[python]>=0.24.0",
    "mkdocs-monorepo-plugin>=1.0.5",  # Phase 1
    "mkdocs-awesome-pages-plugin>=2.9.0",
    "mkdocs-git-revision-date-localized-plugin>=1.2.0",
    "mkdocs-minify-plugin>=0.8.0",
    "pymdown-extensions>=10.7"
]
```

### 5.2 MkDocs Konfiguration

#### 5.2.1 Paket-spezifische mkdocs.yml (z.B. questra-data/mkdocs.yml)

```yaml
site_name: Questra Data
site_description: Python Client für Dyno GraphQL API
site_url: https://docs.example.com/questra-data/

# Repository
repo_url: https://dev.azure.com/seven2one/Seven2one.Questra/_git/S2O.PoC.Questra.Python.Packages
edit_uri: edit/main/questra-data/docs/

# Theme
theme:
  name: material
  palette:
    # Light mode
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate

# Plugins
plugins:
  - search:
      lang: de
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          options:
            docstring_style: google
            show_source: true
            show_root_heading: true
            show_root_full_path: false
            members_order: source
            separate_signature: true
            show_signature_annotations: true
            signature_crossrefs: true
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
  - minify:
      minify_html: true

# Markdown Extensions
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - attr_list
  - md_in_html
  - toc:
      permalink: true

# Navigation
nav:
  - Home: index.md
  - Erste Schritte:
      - Installation: getting-started/installation.md
      - Quickstart: getting-started/quickstart.md
      - Authentifizierung: getting-started/authentication.md
  - Tutorials:
      - Grundlagen: tutorials/basics.md
      - GraphQL Operationen: tutorials/graphql-operations.md
      - REST API: tutorials/rest-api.md
      - Zeitreihen: tutorials/timeseries.md
      - Datei-Upload: tutorials/file-upload.md
  - API Referenz:
      - Client: api/client.md
      - Models: api/models.md
      - Operations: api/operations.md
      - Transport: api/transport.md
  - Guides:
      - Best Practices: guides/best-practices.md
      - Error Handling: guides/error-handling.md
      - Logging: guides/logging.md
  - Changelog: changelog.md

# Extra
extra:
  version:
    provider: mike  # Für Versionierung
  social:
    - icon: fontawesome/brands/azure-devops
      link: https://dev.azure.com/seven2one
```

#### 5.2.2 Zentrale mkdocs.yml (Root-Level)

```yaml
site_name: Questra Python SDK
site_description: Komplette Dokumentation für alle Questra Python Pakete
site_url: https://docs.example.com/

# Theme (identisch zu Paket-Konfiguration)
theme:
  name: material
  # ... (wie oben)

# Plugins
plugins:
  - search
  - monorepo:  # Ermöglicht Zusammenführung mehrerer Dokumentationen
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google
  - awesome-pages  # Automatische Navigation aus Ordnerstruktur

# Navigation
nav:
  - Home: index.md
  - Übersicht:
      - Architektur: architecture.md
      - Authentifizierung: authentication-overview.md
  - Pakete:
      - Questra Data: '!include ./questra-data/mkdocs.yml'
      - Questra Authentication: '!include ./questra-authentication/mkdocs.yml'
  - Entwicklung:
      - Contributing: contributing.md
      - Development Setup: development.md
```

### 5.3 Dokumentations-Struktur pro Paket

```
questra-data/docs/
├── index.md                          # Paket-Übersicht
├── getting-started/
│   ├── installation.md               # pip/poetry install Anleitung
│   ├── quickstart.md                 # 5-Minuten-Beispiel
│   └── authentication.md             # Auth-Setup
├── tutorials/
│   ├── basics.md                     # Grundkonzepte
│   ├── graphql-operations.md         # Queries & Mutations
│   ├── rest-api.md                   # REST-Endpunkte
│   ├── timeseries.md                 # Zeitreihen-Handling
│   └── file-upload.md                # Datei-Operationen
├── api/
│   ├── client.md                     # QuestraData Klasse
│   ├── models.md                     # Datenmodelle
│   ├── operations.md                 # Operations Klassen
│   └── transport.md                  # Transport Layer
├── guides/
│   ├── best-practices.md             # Do's and Don'ts
│   ├── error-handling.md             # Exception Handling
│   ├── logging.md                    # Logging Konfiguration
│   └── performance.md                # Performance-Tipps
├── examples/
│   ├── basic-usage.md                # Einfache Beispiele
│   ├── advanced-usage.md             # Fortgeschrittene Beispiele
│   └── integration.md                # Integration in bestehende Projekte
└── changelog.md                      # Versions-Historie
```

### 5.4 API-Dokumentation aus Docstrings

#### Beispiel: api/client.md

```markdown
# QuestraData Client

Die Hauptklasse für den Zugriff auf die Dyno API.

::: questra_data.QuestraData
    options:
      show_root_heading: true
      show_source: true
      members:
        - __init__
        - queries
        - mutations
        - inventory
        - timeseries
        - files
        - audit
        - execute_raw
        - is_authenticated
        - reauthenticate
```

#### Beispiel: api/models.md

```markdown
# Datenmodelle

## Inventory Models

::: questra_data.models.Inventory
    options:
      show_root_heading: true
      members: true

::: questra_data.models.InventoryType
    options:
      show_root_heading: true
      members: true

## TimeSeries Models

::: questra_data.models.TimeSeriesValue
    options:
      show_root_heading: true
      members: true
```

## 6. CI/CD Integration

### 6.1 GitHub Actions / Azure DevOps Pipeline

```yaml
# .github/workflows/docs.yml oder azure-pipelines.yml

name: Documentation

on:
  push:
    branches:
      - main
      - develop
  pull_request:
    branches:
      - main

jobs:
  build-docs:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Für git-revision-date-plugin

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install Poetry
        uses: snok/install-poetry@v1
        with:
          version: 2.0.0

      - name: Install Dependencies
        run: |
          poetry install --with docs

      - name: Build Documentation
        run: |
          poetry run mkdocs build --strict

      - name: Deploy to GitHub Pages (nur main branch)
        if: github.ref == 'refs/heads/main'
        run: |
          poetry run mkdocs gh-deploy --force

      # Optional: Deploy Preview für PRs
      - name: Deploy Preview
        if: github.event_name == 'pull_request'
        uses: netlify/actions/cli@master
        with:
          args: deploy --dir=site --alias=${{ github.event.pull_request.number }}
        env:
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
```

### 6.2 Multi-Version Dokumentation

```bash
# Versionierung mit mike (für MkDocs)

# Neue Version deployen
poetry run mike deploy 0.1.7 latest -u

# Ältere Version deployen
poetry run mike deploy 0.1.6

# Version als Default setzen
poetry run mike set-default latest

# Versionen auflisten
poetry run mike list
```

**mike-Konfiguration in mkdocs.yml:**

```yaml
extra:
  version:
    provider: mike
    default: latest
```

## 7. Prozess und Workflow

### 7.1 Entwickler-Workflow

```mermaid
graph TD
    A[Code-Änderung] --> B[Docstrings schreiben/aktualisieren]
    B --> C[Manuelle Docs aktualisieren falls nötig]
    C --> D[Lokale Preview: mkdocs serve]
    D --> E{Docs OK?}
    E -->|Nein| B
    E -->|Ja| F[Commit & Push]
    F --> G[CI Pipeline startet]
    G --> H[Docs werden gebaut]
    H --> I{Build erfolgreich?}
    I -->|Nein| J[Fix Docs]
    J --> D
    I -->|Ja| K[Deployment]
    K --> L[Docs online verfügbar]
```

### 7.2 Lokale Entwicklung

```bash
# In Paket-Verzeichnis wechseln
cd questra-data/

# Poetry Environment mit Docs-Dependencies
poetry install --with docs

# Lokalen Dev-Server starten
poetry run mkdocs serve

# Browser öffnet http://127.0.0.1:8000
# Live-Reload bei Änderungen

# Build testen
poetry run mkdocs build

# Build mit Strict-Mode (Fehler bei Warnungen)
poetry run mkdocs build --strict
```

### 7.3 Dokumentations-Checkliste für neue Features

- [ ] Docstrings im Google-Style für alle öffentlichen Klassen/Funktionen
- [ ] Type Hints für alle Parameter und Return Values
- [ ] Beispiel in Docstring (Beispiel-Sektion)
- [ ] Tutorial für komplexe Features
- [ ] API-Referenz-Seite aktualisiert
- [ ] Changelog-Eintrag erstellt
- [ ] Code-Beispiele getestet
- [ ] Screenshots/Diagramme hinzugefügt (falls relevant)

## 8. Docstring-Konventionen

### 8.1 Google-Style Docstrings (Empfohlen)

```python
def get_inventories(
    self,
    first: Optional[int] = None,
    after: Optional[str] = None,
    name: Optional[str] = None,
) -> tuple[list[Inventory], PageInfo]:
    """
    Ruft eine Liste von Inventories ab.

    Diese Methode verwendet Pagination und ermöglicht Filterung nach Name.
    Die Ergebnisse werden als Tupel mit Daten und Pagination-Info zurückgegeben.

    Args:
        first: Maximale Anzahl der Ergebnisse (Standard: 100)
        after: Cursor für Pagination (Base64-kodiert)
        name: Filter nach Inventory-Name (case-insensitive substring match)

    Returns:
        Tupel aus zwei Elementen:
            - list[Inventory]: Liste der gefundenen Inventories
            - PageInfo: Pagination-Informationen mit hasNextPage und endCursor

    Raises:
        ValueError: Wenn first negativ ist oder after ungültig
        ConnectionError: Bei Netzwerkproblemen
        GraphQLError: Bei GraphQL-spezifischen Fehlern

    Example:
        Basic usage:

        ```python
        from questra_data import QuestraData
        from questra_authentication import QuestraAuthentication

        # Client initialisieren
        auth = QuestraAuthentication(...)
        client = QuestraData(graphql_url="...", auth_client=auth)

        # Erste 10 Inventories abrufen
        inventories, page_info = client.queries.get_inventories(first=10)

        for inv in inventories:
            print(f"Inventory: {inv.name} (ID: {inv.id})")

        # Pagination
        if page_info.has_next_page:
            next_batch, _ = client.queries.get_inventories(
                first=10,
                after=page_info.end_cursor
            )
        ```

        Filtering by name:

        ```python
        # Nach Name filtern
        user_inventories, _ = client.queries.get_inventories(name="User")
        ```

    See Also:
        - get_inventory(): Abrufen eines einzelnen Inventories
        - create_inventory(): Erstellen eines neuen Inventories

    Note:
        Die Pagination ist cursor-basiert. Der Cursor muss nicht
        manuell dekodiert werden.

    Warning:
        Bei sehr großen Datensätzen (>1000 Einträge) sollte
        Pagination verwendet werden um Timeouts zu vermeiden.
    """
    # Implementation
    pass
```

### 8.2 Docstring-Sektionen

**Pflicht-Sektionen:**
- Kurzbeschreibung (erste Zeile)
- Args (bei Parametern)
- Returns (außer bei None)

**Optionale Sektionen:**
- Raises (bei Exceptions)
- Example (empfohlen für komplexe Funktionen)
- See Also (für verwandte Funktionen)
- Note (wichtige Hinweise)
- Warning (Warnungen)
- Attributes (für Klassen)

## 9. Hosting und Deployment

### 9.1 Hosting-Optionen

| Option | Kosten | Eignung | Vorteile | Nachteile |
|--------|--------|---------|----------|-----------|
| **GitHub Pages** | Kostenlos | Öffentliche Repos | Einfach, kostenlos | Nur öffentlich |
| **GitLab Pages** | Kostenlos | Öffentlich & Privat | Kostenlos auch privat | Weniger Features |
| **Azure Static Web Apps** | Kostenlos-Tier | Enterprise | Azure-Integration | Setup aufwändiger |
| **Netlify** | Kostenlos-Tier | Alle | Preview-Deployments | Limitertes Free-Tier |
| **Read the Docs** | Kostenlos | Open Source | CI-Integration | Nur für Open Source optimal |
| **Self-Hosted** | Infrastruktur | Enterprise | Volle Kontrolle | Wartungsaufwand |

### 9.2 Empfehlung für Seven2One

**Option 1 (Intern)**: Azure Static Web Apps
- Integration mit Azure DevOps
- Internes Hosting
- Authentifizierung möglich

**Option 2 (Öffentlich)**: GitHub Pages + Custom Domain
- docs.seven2one.de/questra-python/
- Kostenlos und einfach

### 9.3 Deployment-Setup (Azure Static Web Apps)

```yaml
# azure-pipelines-docs.yml

trigger:
  branches:
    include:
      - main
  paths:
    include:
      - docs/
      - '*/docs/'
      - mkdocs.yml
      - '*/mkdocs.yml'

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: '3.12'

  - script: |
      pip install poetry
      poetry install --with docs
    displayName: 'Install Dependencies'

  - script: |
      poetry run mkdocs build --strict
    displayName: 'Build Documentation'

  - task: AzureStaticWebApp@0
    inputs:
      app_location: 'site'
      skip_app_build: true
      azure_static_web_apps_api_token: $(deployment_token)
```

## 10. Wartung und Best Practices

### 10.1 Qualitätssicherung

**Automatische Checks:**
```yaml
# In CI/CD Pipeline

- name: Check Docs Links
  run: poetry run mkdocs build --strict

- name: Spell Check (optional)
  run: |
    npm install -g cspell
    cspell "docs/**/*.md"

- name: Check Docstring Coverage
  run: |
    poetry add --group dev interrogate
    poetry run interrogate -vv src/
```

**interrogate-Konfiguration in pyproject.toml:**
```toml
[tool.interrogate]
ignore-init-method = true
ignore-init-module = false
ignore-magic = false
ignore-semiprivate = false
ignore-private = false
ignore-property-decorators = false
ignore-module = false
ignore-nested-functions = false
fail-under = 80  # 80% Docstring-Coverage erforderlich
exclude = ["tests", "docs"]
verbose = 2
```

### 10.2 Style Guide für Dokumentation

**Markdown-Konventionen:**
- ATX-Style Headers (`#` statt underline)
- Fenced Code Blocks mit Sprache-Annotation
- Relative Links für interne Referenzen
- Ein Satz pro Zeile (erleichtert Diffs)

**Beispiel:**
```markdown
# Installation

## Voraussetzungen

Stellen Sie sicher, dass Python 3.10+ installiert ist:

```bash
python --version
```

## Installation via pip

```bash
pip install questra-data
```

Siehe auch [Authentifizierung](authentication.md) für weitere Schritte.
```

### 10.3 Review-Prozess

**Pull Request Checkliste für Docs:**
- [ ] Alle neuen/geänderten Funktionen dokumentiert
- [ ] Docstring Coverage ≥ 80%
- [ ] Build ohne Fehler/Warnungen
- [ ] Links funktionieren
- [ ] Code-Beispiele getestet
- [ ] Rechtschreibung geprüft
- [ ] Screenshots aktuell

## 11. Roadmap

### Phase 1: Setup (Woche 1-2)
- [x] Tool-Auswahl finalisieren
- [ ] MkDocs + Material Theme Setup
- [ ] Basis-Struktur für questra-data
- [ ] CI/CD Pipeline aufsetzen
- [ ] Erstes Deployment

### Phase 2: Content (Woche 3-4)
- [ ] API-Dokumentation generieren
- [ ] Quickstart Guide schreiben
- [ ] Tutorials erstellen
- [ ] Code-Beispiele dokumentieren

### Phase 3: Integration (Woche 5-6)
- [ ] questra-authentication integrieren
- [ ] Zentrale Docs-Seite aufsetzen
- [ ] Cross-Package Navigation
- [ ] Versionierung implementieren

### Phase 4: Optimierung (Woche 7-8)
- [ ] Suchfunktion optimieren
- [ ] Analytics integrieren
- [ ] Feedback-Mechanismus
- [ ] Performance-Optimierung

### Phase 5: Rollout (Woche 9-10)
- [ ] Team-Training
- [ ] Dokumentations-Guidelines finalisieren
- [ ] Review-Prozess etablieren
- [ ] Go-Live

## 12. Kosten und Ressourcen

### 12.1 Einmalige Kosten
- Setup: ~2 Entwicklertage
- Initiale Content-Erstellung: ~5 Entwicklertage
- CI/CD Integration: ~1 Entwicklertag
- **Gesamt: ~8 Entwicklertage**

### 12.2 Laufende Kosten
- Wartung pro Feature: +30 Minuten (Docstrings + Beispiel)
- Docs-Review: ~15 Minuten pro PR
- Quartalsweise Docs-Refresh: ~1 Tag
- Hosting: 0€ (GitHub Pages) bis ~10€/Monat (Netlify Pro)

### 12.3 ROI
- Reduktion Support-Anfragen: -30%
- Schnellere Onboarding-Zeit: -50%
- Höhere Code-Qualität durch Review-Fokus
- Bessere externe Wahrnehmung

## 13. Nächste Schritte

### Sofort:
1. Entscheidung Tool-Stack: **MkDocs empfohlen**
2. Repository-Struktur festlegen: **Monorepo für Start**
3. Pilot-Projekt: **questra-data** als erstes Paket

### Diese Woche:
1. Dependencies installieren (`poetry add --group docs mkdocs mkdocs-material mkdocstrings`)
2. Basis-mkdocs.yml erstellen
3. Erste API-Dokumentation generieren
4. Lokales `mkdocs serve` testen

### Nächster Sprint:
1. CI/CD Pipeline implementieren
2. Deployment-Target festlegen
3. Content-Erstellung beginnen
4. Team-Schulung planen

## 14. Anhang

### 14.1 Weitere Ressourcen

- [MkDocs Documentation](https://www.mkdocs.org/)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
- [mkdocstrings](https://mkdocstrings.github.io/)
- [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
- [PEP 257 - Docstring Conventions](https://peps.python.org/pep-0257/)

### 14.2 Beispiel-Projekte mit ähnlichem Setup

- [FastAPI](https://fastapi.tiangolo.com/) - MkDocs + Material
- [Pydantic](https://docs.pydantic.dev/) - MkDocs + Material
- [mkdocstrings](https://mkdocstrings.github.io/) - Selbst-Dokumentation

### 14.3 Alternative Ansätze

**Jupyter Book**: Gut für wissenschaftliche Pakete mit Notebooks
**Docusaurus**: React-basiert, gut für sehr große Projekte
**VuePress**: Vue-basiert, gute Komponenten-Unterstützung
