initial

README.md

@@ -0,0 +1,128 @@
+# Forgejo Issues zu Markdown Export - Anleitung
+
+Diese Anleitung erklärt, wie du den Forgejo-to-Markdown Exporter einrichten und verwenden kannst, um Issues in Markdown-Dateien zu exportieren und sie für Knowledge-Management-Tools wie MSTY zu nutzen.
+
+## Überblick
+
+Der Exporter bietet folgende Funktionen:
+
+- Export aller Issues eines Repositories oder einer Organisation in Markdown-Dateien
+- Inkrementelle Updates (nur geänderte Issues werden aktualisiert)
+- Einbeziehung von Kommentaren und Metadaten
+- Formatierung als strukturierte Markdown-Dokumente
+- Erstellung einer Indexdatei für den einfachen Zugriff
+
+## Installation
+
+### Voraussetzungen
+
+- Python 3.11 oder höher
+- Internetverbindung zum Forgejo-Server
+- Berechtigungen zum Lesen der Forgejo-Issues
+
+### Einrichtung
+
+1. Speichere das Skript 
+Am besten installierst du den Exporter über den befehl `git clone https://git.rpi-virtuell.de/joachim-happel/git_issue_importer.git` danach wechselst eu in das Verzeichnis mit `cd git_issue_importer`
+
+2. Kopiere die Datei .env.template nach .env und setze die URl zu deiner forgejo Instanz:
+
+```text
+FORGEJO_URL = "https://git.rpi-virtuell.de"
+FORGEJO_TOKEN = "dein-token"
+```
+den Token kannst du unter  https://git.rpi-virtuell.de/user/settings/applications generieren
+
+3. Installiere die erforderlichen Abhängigkeiten:
+
+```bash
+pip install requests python-dotenv
+```
+
+
+## Verwendung
+
+### Grundlegende Verwendung
+
+Führe das Skript mit den erforderlichen Parametern aus:
+
+```bash
+python forgejo_exporter.py --owner "Comenius-Institut" --repo "FOERBICO" --output "./forgejo_issues"
+```
+
+### Alle verfügbaren Parameter
+
+```
+--owner    : Repository-Besitzer (Benutzer oder Organisation) [erforderlich]
+--repo     : Repository-Name oder 'all' für alle Repositories [erforderlich]
+--output   : Ausgabeordner für Markdown-Dateien [Standard: ./forgejo_issues]
+--comments : Kommentare einbeziehen [optional Flag]
+--closed   : Geschlossene Issues einbeziehen [optional Flag]
+```
+
+### Beispiele
+
+**Export eines einzelnen Repositories mit Kommentaren:**
+```bash
+python forgejo_exporter.py --owner "Comenius-Institut" --repo "FOERBICO" --output "./forgejo_issues" --comments
+```
+
+**Export aller Repositories einer Organisation inkl. geschlossener Issues:**
+```bash
+python forgejo_exporter.py --owner "Comenius-Institut" --repo "all" --output "./forgejo_issues" --closed
+```
+
+**Export mit allen Optionen:**
+```bash
+python forgejo_exporter.py --owner "Comenius-Institut" --repo "FOERBICO" --output "./forgejo_issues" --comments --closed
+```
+
+## Automatisierung
+
+Um die Aktualisierung zu automatisieren, kannst du das bereitgestellte Bash-Skript verwenden:
+
+1. Speichere das Bash-Skript als `update_forgejo.sh`
+2. Mache es ausführbar: `chmod +x update_forgejo.sh`
+3. Passe die Einstellungen im Skript an (Repository-Besitzer, Repository-Name)
+4. Führe es manuell aus oder richte einen Cron-Job ein
+
+### Einrichtung eines Cron-Jobs für regelmäßige Updates
+
+Öffne die Crontab-Konfiguration:
+```bash
+crontab -e
+```
+
+Füge eine Zeile für tägliche Aktualisierungen hinzu:
+```
+# Aktualisiere Forgejo-Issues jeden Tag um 3:00 Uhr
+0 3 * * * /pfad/zu/update_forgejo.sh
+```
+
+## Ausgabestruktur
+
+Nach der Ausführung des Skripts enthält der Ausgabeordner folgende Dateien:
+
+- `index.md`: Eine Übersicht aller Issues, gruppiert nach Repository
+- `_metadata.json`: Metadaten für inkrementelle Updates (nicht löschen!)
+- Einzelne Markdown-Dateien für jedes Issue, mit dem Namensformat:
+  `{repository_owner}_{repository_name}__issue_{number}_{title}.md`
+
+### Struktur einer Issue-Datei
+
+Jede generierte Markdown-Datei enthält:
+
+1. **Titel und Issue-ID**
+2. **Metadaten** (Repository, Autor, Status, Daten, URL)
+3. **Labels** (falls vorhanden)
+4. **Milestone** (falls vorhanden)
+5. **Beschreibung** des Issues
+6. **Kommentare** (wenn mit `--comments` aktiviert)
+
+## Integration mit Knowledge-Management-Tools
+
+### Verwendung mit MSTY
+
+1. Wähle den Ausgabeordner als Knowledge Stack in MSTY
+2. Klicke auf Compose (kann einige Minuten dauern)
+3. Führe das Update-Skript und Compose regelmäßig aus, um die Wissensdatenbank aktuell zu halten