info
4733ea6b82
Fügt OpenWiki-Setup (Workflow, Seiten, CLAUDE.md-Verweis) und AGENTS.md hinzu, damit wiederkehrende Code-Dokumentation automatisch gepflegt wird. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
87 lines
4.0 KiB
Markdown
87 lines
4.0 KiB
Markdown
---
|
||
type: Quickstart
|
||
title: DocuMentor – Schnellstart
|
||
description: Einstiegspunkt in die Dokumentation. Überblick über DocuMentor, einer PySide6-Desktop-App für XSL-Transformationsverwaltung und PDF-Generierung.
|
||
tags: [xsl, pdf, pyside6, desktop-app, transformation]
|
||
---
|
||
|
||
# DocuMentor – Schnellstart
|
||
|
||
**DocuMentor** ist eine PySide6-basierte Desktop-Anwendung zur Verwaltung und Validierung von XSL-Transformationen mit automatischer PDF-Generierung. Sie richtet sich an Entwickler, die kontinuierlich XSL-Stylesheets pflegen und die Auswirkungen auf generierte PDF-Dokumente nachvollziehen müssen.
|
||
|
||
## Was ist DocuMentor?
|
||
|
||
Der primäre Einsatz ist die Weiterentwicklung von PDF-Dokumenten in **Flexnow** (Prüfungsverwaltungs-Software). Die Basis bilden ca. 100 XSL-Dateien, die über `<xsl:import/>` und `<xsl:include/>` miteinander verknüpft sind. Änderungen an einer XSL-Datei können sich auf viele andere auswirken. DocuMentor hilft, diese Auswirkungen durch automatisierte Transformation und PDF-Vergleich zu kontrollieren.
|
||
|
||
### Kern-Features
|
||
|
||
- **Hierarchische Projektverwaltung** – Baumstruktur für Transformations-Workflows mit verschachtelten Knoten
|
||
- **Asynchrone Batch-Verarbeitung** – Große Mengen von XML-Dateien im Hintergrund mit Fortschrittsanzeige
|
||
- **Parallele Worker-Pools** – Persistente JVM-Prozesse für Saxon (XSLT) und Apache FOP (PDF) eliminieren JVM-Startup-Overhead
|
||
- **Duplikatserkennung** – Hash-basierte (blake2b) Erkennung identischer XML-Dateien
|
||
- **PDF-Vergleichsansicht** – Drei-Panel-Ansicht (Referenz, Diff, Neu) mit Alpha-Blending und Zoom
|
||
- **PostgreSQL-Integration** – Datenbankanbindung mit Polars/ConnectorX
|
||
- **XSL-Abhängigkeitsgraph** – Visualisierung von `<xsl:import/>`- und `<xsl:include/>`-Beziehungen via vis.js
|
||
- **Plattformübergreifend** – Linux, Windows, macOS
|
||
|
||
## Installation
|
||
|
||
### Voraussetzungen
|
||
|
||
- Python 3.13+
|
||
- [uv](https://github.com/astral-sh/uv) Paketmanager
|
||
- OpenJDK/JRE (für Saxon und Apache FOP)
|
||
|
||
### Abhängigkeiten
|
||
|
||
```bash
|
||
uv sync
|
||
```
|
||
|
||
### Externe Tools
|
||
|
||
| Tool | Zweck | Download |
|
||
|------|-------|----------|
|
||
| **Saxon-HE** | XSLT 3.0 Prozessor | [saxonica.com](https://www.saxonica.com/download/) |
|
||
| **Apache FOP** | PDF-Generierung aus XSL-FO | [xmlgraphics.apache.org](https://xmlgraphics.apache.org/fop/download.html) |
|
||
| **diff-pdf** | PDF-Vergleich | [GitHub](https://github.com/vslavik/diff-pdf) |
|
||
| **OpenJDK** | JVM für Saxon/FOP Worker-Pools | [Eclipse Temurin](https://adoptium.net) |
|
||
|
||
## Anwendung starten
|
||
|
||
```bash
|
||
uv run python src/main.py
|
||
```
|
||
|
||
Beim ersten Start öffnet sich der Einstellungsdialog, in dem die externen Tools (Java VM, Saxon JAR, Apache FOP, diff-pdf, XSL-Verzeichnis, PostgreSQL) konfiguriert werden.
|
||
|
||
## Typischer Workflow
|
||
|
||
1. Entwickler ändert XSL-Dateien
|
||
2. Transformation in DocuMentor starten
|
||
3. PDF-Diff begutachten: Wurden die richtigen PDFs geändert?
|
||
4. Prüfen: Entspricht die Änderung der Erwartung?
|
||
5. Ggf. zurück zu Schritt 1
|
||
|
||
## Konfigurationsorte
|
||
|
||
| Plattform | Pfad |
|
||
|-----------|------|
|
||
| Linux | `~/.config/DocuMentor/config.json` |
|
||
| Windows | `%APPDATA%\DocuMentor\config.json` |
|
||
| macOS | `~/Library/Application Support/DocuMentor/config.json` |
|
||
|
||
Projektdaten werden pro Projekt in `project.yaml` gespeichert.
|
||
|
||
## Wiki-Struktur
|
||
|
||
- [Architektur-Überblick](architecture/overview.md) – PySide6-Mixin-Architektur, UI-Pattern, Thread-Modell, Konfigurationssystem
|
||
- [Transformations-Pipeline](workflows/transformation-pipeline.md) – XML→FO→PDF→Diff, Worker-Pools, XSL-Abhängigkeitsgraph, Entscheidungslogik
|
||
- [Datenmodelle & Konfiguration](data-models.md) – AppSettings, Project, ProjectData, TreeNode/XslFile/XmlFile, Hash-System, PostgreSQL
|
||
- [Build & Betrieb](operations.md) – Build-Prozess, MSI/ZIP-Distribution, Tests, Code-Style, Lizenzen
|
||
|
||
## Backlog
|
||
|
||
- **Web-Seite** (`web/`): Statische HTML-Landingpage mit Datenschutz/Impressum – nicht Teil der Anwendungslogik, bei Bedarf separat dokumentieren.
|
||
- **Skills** (`skills/`): Nur `write-connector` (OpenWiki-Skill), nicht projektspezifisch.
|