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.
|