Skip to content
Snippets Groups Projects
Commit 77e2285b authored by CookieNinjaLabs's avatar CookieNinjaLabs
Browse files

Verfeinerung der README-Struktur und der Klarheit der Projektbeschreibung. 

Die README wurde aktualisiert, um die Lesbarkeit zu verbessern, indem die Formatierung verfeinert, die Einrückung korrigiert und die Beschreibungen der Projekt-Setup-Schritte, des Technologie-Stacks und der Projektstruktur verbessert wurden.
parent 4e3f165a
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 109 additions and 93 deletions
README.md
+ 109
− 93
View file @ 77e2285b
# Duisburg Open Data Visualisierer (DOD-Vis)
**Version:** Prototyp (MVP) - Stand: Mai 2025
**Dauer des initialen Sprints:** 1,5 Monate
**Dauer des Projekts:** ca. 1,5 Monate
## Inhaltsverzeichnis
1. [Über dieses Projekt](#über-dieses-projekt)
2. [Voraussetzungen](#voraussetzungen)
3. [Initiales Setup für Teammitglieder mit `uv`](#initiales-setup-für-teammitglieder-mit-uv)
......@@ -15,13 +16,19 @@
9. [Zen of Python](#zen-of-python)
## Über dieses Projekt
DOD-Vis ist ein Prototyp, der im Rahmen eines Design Science Research (DSR) Projekts entwickelt wird. Ziel ist es, die Machbarkeit der automatisierten Konvertierung von CSV-Datensätzen aus dem Open Data Portal Duisburg in RDF und deren anschließende Visualisierung als interaktiven Graphen zu demonstrieren.
Das Projekt adressiert das Problem, dass CSV-Daten inhärent semantische Beschreibungen und Verknüpfungsmöglichkeiten fehlen, wodurch tiefere Zusammenhänge oft verborgen bleiben. DOD-Vis soll exemplarisch zeigen, wie diese Daten durch RDF-Transformation und Graphenvisualisierung aufgewertet und explorierbarer gemacht werden können.
DOD-Vis ist ein Prototyp, der im Rahmen eines mini Design Science Research (DSR) Projekts entwickelt wird. Ziel ist es,
die Machbarkeit der automatisierten Konvertierung von CSV-Datensätzen aus dem Open Data Portal Duisburg in RDF und deren
anschließende Visualisierung als interaktiven Graphen zu demonstrieren.
Das Projekt adressiert das Problem, dass CSV-Daten inhärent semantische Beschreibungen und Verknüpfungsmöglichkeiten
fehlen, wodurch tiefere Zusammenhänge oft verborgen bleiben. DOD-Vis soll exemplarisch zeigen, wie diese Daten durch
RDF-Transformation und Graphenvisualisierung aufgewertet und explorierbarer gemacht werden können.
Weitere Details finden sich im [Projekt Exposé](docs/OpenData_Expose.pdf).
## Voraussetzungen
Bevor du beginnst, stelle sicher, dass die folgenden Werkzeuge auf deinem System installiert sind:
* **Python:** Version 3.9 oder höher.
......@@ -40,19 +47,19 @@ Bevor du beginnst, stelle sicher, dass die folgenden Werkzeuge auf deinem System
Folge diesen Schritten, um das Projekt lokal einzurichten:
1. **Repository klonen:**
```bash
git clone https://gitlab.hsrw.eu/31450/dod-vis.git
cd dod-vis
```
1. **Repository klonen:**
```bash
git clone https://gitlab.hsrw.eu/31450/dod-vis.git
cd dod-vis
```
2. **Virtuelle Umgebung mit `uv` erstellen:**
`uv` erstellt standardmäßig ein Verzeichnis namens `.venv` im Projektstamm.
```bash
uv venv
```
2. **Virtuelle Umgebung mit `uv` erstellen:**
`uv` erstellt standardmäßig ein Verzeichnis namens `.venv` im Projektstamm.
```bash
uv venv
```
3. **Virtuelle Umgebung aktivieren:**
3. **Virtuelle Umgebung aktivieren:**
* Für Linux/macOS:
```bash
source .venv/bin/activate
......@@ -65,89 +72,96 @@ Folge diesen Schritten, um das Projekt lokal einzurichten:
```cmd
.venv\Scripts\activate.bat
```
Nach erfolgreicher Aktivierung sollte deiner Shell-Prompt `(.venv)` vorangestellt sein.
4. **Abhängigkeiten installieren:**
Die Projektabhängigkeiten sind in der Datei `pyproject.toml` im Projektstamm definiert.
```bash
# Installiert die im pyproject.toml definierten Abhängigkeiten
# und das Projekt selbst (falls es als Paket gebaut werden soll).
# Für die Entwicklung ist dies ein gängiger Befehl.
# uv pip install .
# Alternativ, wenn ein `uv.lock` Datei vorhanden ist und exakt diese Versionen
# installiert werden sollen (empfohlen für reproduzierbare Builds):
uv sync
```
*Hinweis: Frontend-Bibliotheken (z.B. Vis.js) werden typischerweise über Djangos Static Files Handling bereitgestellt oder über ein CDN eingebunden.*
5. **(Nur beim allerersten Setup nach dem Klonen) Datenbank-Migrationen anwenden:**
Auch wenn wir für den MVP vielleicht keine komplexen Modelle nutzen, ist dies eine Standard-Django-Praxis.
```bash
python manage.py migrate
```
Nach erfolgreicher Aktivierung sollte deiner Shell-Prompt `(.venv)` vorangestellt sein.
4. **Abhängigkeiten installieren:**
Die Projektabhängigkeiten sind in der Datei `pyproject.toml` im Projektstamm definiert.
```bash
# Installiert die im pyproject.toml definierten Abhängigkeiten
# und das Projekt selbst (falls es als Paket gebaut werden soll).
# Für die Entwicklung ist dies ein gängiger Befehl.
# uv pip install .
# Alternativ, wenn ein `uv.lock` Datei vorhanden ist und exakt diese Versionen
# installiert werden sollen (empfohlen für reproduzierbare Builds):
uv sync
```
*Hinweis: Frontend-Bibliotheken (z.B. Vis.js) werden typischerweise über Djangos Static Files Handling bereitgestellt
oder über ein CDN eingebunden.*
5. **(Nur beim allerersten Setup nach dem Klonen) Datenbank-Migrationen anwenden:**
Auch wenn wir für den MVP vielleicht keine komplexen Modelle nutzen, ist dies eine Standard-Django-Praxis.
```bash
python manage.py migrate
```
## Anwendung starten
Der DOD-Vis Prototyp mit Django wird über den `manage.py` Skript gestartet.
1. **Django Entwicklungsserver starten:**
Stelle sicher, dass die virtuelle Umgebung aktiviert ist.
```bash
python manage.py runserver --settings=openData.settings.development
```
Der Server startet standardmäßig auf `http://127.0.0.1:8000/`. Beachte die Ausgabe im Terminal für die genaue URL.
2. **Anwendung im Browser aufrufen:**
Öffne die im Terminal angezeigte URL (z.B. `http://127.0.0.1:8000/`) in deinem Webbrowser. Die Hauptseite der Anwendung wird über eine Django-View und ein Template bereitgestellt (z.B. unter einer URL wie `/visualizer/`).
3. **Statische Dateien sammeln (Static Files):**
Während der Entwicklung mit `DEBUG = True` (Standard in `development.py`) sollte Django statische Dateien automatisch aus den `static` Verzeichnissen der Apps bereitstellen. Falls jedoch statische Dateien (CSS, JS, Bilder aus der App oder von Drittanbieter-Apps) nicht korrekt geladen werden oder das Verhalten für Deployments geteste werden soll, muss `collectstatic` ausgeführt werden:
```bash
python manage.py collectstatic --settings=openData.settings.development --noinput
```
Das `--noinput` Flag verhindert Rückfragen. Dieser Befehl sammelt alle statischen Dateien in dem Verzeichnis, das in `STATIC_ROOT` in euren `openData.settings.development` definiert ist. **Dies muss ggf. nach Änderungen an statischen Dateien oder bei Problemen mit deren Auslieferung erneut ausgeführt werden.**
1. **Django Entwicklungsserver starten:**
Stelle sicher, dass die virtuelle Umgebung aktiviert ist.
```bash
python manage.py runserver --settings=openData.settings.development
```
Der Server startet standardmäßig auf `http://127.0.0.1:8000/`. Beachte die Ausgabe im Terminal für die genaue URL.
2. **Anwendung im Browser aufrufen:**
Öffne die im Terminal angezeigte URL (z.B. `http://127.0.0.1:8000/`) in deinem Webbrowser. Die Hauptseite der
Anwendung wird über eine Django-View und ein Template bereitgestellt (z.B. unter einer URL wie `/visualizer/`).
3. **Statische Dateien sammeln (Static Files):**
Während der Entwicklung mit `DEBUG = True` (Standard in `development.py`) sollte Django statische Dateien automatisch
aus den `static` Verzeichnissen der Apps bereitstellen. Falls jedoch statische Dateien (CSS, JS, Bilder aus der App
oder von Drittanbieter-Apps) nicht korrekt geladen werden oder das Verhalten für Deployments geteste werden soll,
muss `collectstatic` ausgeführt werden:
```bash
python manage.py collectstatic --settings=openData.settings.development --noinput
```
Das `--noinput` Flag verhindert Rückfragen. Dieser Befehl sammelt alle statischen Dateien in dem Verzeichnis, das in
`STATIC_ROOT` in euren `openData.settings.development` definiert ist. **Dies muss ggf. nach Änderungen an statischen
Dateien oder bei Problemen mit deren Auslieferung erneut ausgeführt werden.**
## Projektstruktur (Vorschlag)
```bash
project_root/
├── manage.py
├── pyproject.toml
├── README.md
├── uv.lock
├── .env
├── .gitignore
├── openData/
│ ├── __init__.py
│ ├── settings/
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── development.py
│ │ └── production.py
│ ├── urls.py
│ ├── asgi.py
│ └── wsgi.py
├── apps/
│ ├── __init__.py
│ ├── dod_vis/
│ │ ├── __init__.py
│ │ ├── models.py
│ │ ├── serializers.py
│ │ ├── views.py
│ │ ├── urls.py
│ │ └── tests/
│ └── api/
│ ├── __init__.py
│ ├── v1/
│ │ ├── __init__.py
│ │ ├── urls.py
│ │ └── views.py
│ └── tests/
├── docs/
├── static/
├── media/
└── templates/
project_root/ # Hauptverzeichnis des Projekts
├── manage.py # Django-Kommandozeilen-Tool für administrative Aufgaben
├── pyproject.toml # Python-Projektmetadaten und Abhängigkeiten (modernes Setup-Tool)
├── README.md # Projektdokumentation und Setup-Anweisungen
├── uv.lock # Exakte Versionen der Abhängigkeiten für reproduzierbare Builds
├── .env # Umgebungsvariablen (nicht in Git, enthält sensitive Daten)
├── .gitignore # Liste der von Git zu ignorierenden Dateien/Ordner
├── openData/ # Hauptprojektverzeichnis (Django-Projekteinstellungen)
│ ├── __init__.py # Macht das Verzeichnis zu einem Python-Paket
│ ├── settings/ # Einstellungen für verschiedene Umgebungen
│ │ ├── __init__.py # Macht settings zu einem Paket
│ │ ├── base.py # Grundlegende Einstellungen für alle Umgebungen
│ │ ├── development.py # Entwicklungsspezifische Einstellungen (DEBUG=True, etc.)
│ │ └── production.py # Produktionseinstellungen (Sicherheit, Performance)
│ ├── urls.py # Haupt-URL-Konfiguration des Projekts
│ ├── asgi.py # ASGI-Konfiguration für asynchrone Server
│ └── wsgi.py # WSGI-Konfiguration für traditionelle Server
├── apps/ # Verzeichnis für alle Django-Anwendungen
│ ├── __init__.py # Macht apps zu einem Python-Paket
│ ├── dod_vis/ # Hauptanwendung für die Visualisierung
│ │ ├── __init__.py # Macht dod_vis zu einem Paket
│ │ ├── models.py # Datenmodelle/Datenbankschema
│ │ ├── serializers.py # API-Serialisierer für Datenkonvertierung
│ │ ├── views.py # View-Logik und Request-Handling
│ │ ├── urls.py # URL-Routing für die dod_vis App
│ │ └── tests/ # Unit- und Integrationstests für dod_vis
│ └── api/ # Separate API-Anwendung
│ ├── __init__.py # Macht api zu einem Paket
│ ├── v1/ # API Version 1
│ │ ├── __init__.py # Macht v1 zu einem Paket
│ │ ├── urls.py # URL-Routing für API v1
│ │ └── views.py # API-Endpunkte und Logik
│ └── tests/ # Tests für die API
├── docs/ # Projektdokumentation (Architektur, API, etc.)
├── static/ # Statische Dateien (CSS, JS, Bilder)
├── media/ # Benutzer-hochgeladene Dateien
└── templates/ # HTML-Templates für die gesamte Anwendung
```
## Technologie-Stack
......@@ -163,12 +177,15 @@ Wichtige Konfigurationen befinden sich hauptsächlich in `dod_vis_project/settin
* **Allgemeine Django-Settings:** `SECRET_KEY`, `DEBUG`, `ALLOWED_HOSTS`, etc.
* **Datenbank:** (Für den MVP möglicherweise SQLite Standard, ohne große Anpassungen nötig).
* **Static Files:** `STATIC_URL`, `STATICFILES_DIRS` (um Djangos `collectstatic` und das Serving von statischen Dateien aus den App-Verzeichnissen zu ermöglichen).
* **Static Files:** `STATIC_URL`, `STATICFILES_DIRS` (um Djangos `collectstatic` und das Serving von statischen Dateien
aus den App-Verzeichnissen zu ermöglichen).
* **App-spezifische Konfigurationen:**
* URL des DKAN Portals Duisburg.
* IDs/Namen der 1-2 fest vordefinierten CSV-Datensätze.
* Diese können als Variablen in `settings.py` definiert oder direkt in den Modulen der `visualizer`-App (z.B. `dkan_client.py`) verwendet werden.
* **API-Endpunkte:** Werden in `visualizer/views.py` implementiert und über `visualizer/urls.py` sowie `dod_vis_project/urls.py` geroutet.
* Diese können als Variablen in `settings.py` definiert oder direkt in den Modulen der `visualizer`-App (z.B.
`dkan_client.py`) verwendet werden.
* **API-Endpunkte:** Werden in `visualizer/views.py` implementiert und über `visualizer/urls.py` sowie
`dod_vis_project/urls.py` geroutet.
## Mitwirkende
......@@ -177,7 +194,6 @@ Wichtige Konfigurationen befinden sich hauptsächlich in `dod_vis_project/settin
* Jonas **Vieth**
* Kamil **Znamirowski**
## Zen of Python
- Beautiful is better than ugly.
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment