Tabelle für Umsetzungsphasen und Coding Conventions in docu dazu. Projektübersicht und erster Wurf für Folder rein
This commit is contained in:
@@ -1,5 +1,162 @@
|
||||
# Kernkonzepte
|
||||
|
||||
## Projektübersicht
|
||||
|
||||
Sphinx-basiertes Dokumentationssystem für Transport- und Hängefördersysteme.
|
||||
JSON-gesteuerter Build erzeugt aus modularen Textbausteinen mehrsprachige PDF-Dokumentationen (250+ Seiten).
|
||||
Zwei-Repo-Architektur: allgemeine Ressourcen (Base-Repo) + projektspezifische Anpassungen (Projekt-Repo).
|
||||
|
||||
Auftraggeber: Firma Schönenberger
|
||||
Umsetzung: Mista GmbH
|
||||
|
||||
## Architektur
|
||||
|
||||
### Zwei-Repo-Trennung
|
||||
|
||||
- **transport-docs-base** (Gitea): Alle wiederverwendbaren Inhalte – Module, Kapitelgerüste, Assets, Glossar, Sphinx-Extensions, LaTeX-Templates, Hilfsskripte. Semver-versioniert (VERSION-Datei).
|
||||
- **projekt-kunde-xyz** (pro Anlage): anlage.json (ERP-Export), projektspezifische Bilder, Overrides, Zusatzkapitel, conf.py, build.py. Das Base-Repo wird beim Build als Mount/Share unter `transport-docs-base/` bereitgestellt.
|
||||
|
||||
### Technologie-Stack
|
||||
|
||||
| Komponente | Technologie |
|
||||
|------------------|--------------------------------------------------|
|
||||
| Build-System | Sphinx (Python) |
|
||||
| Textformat | reStructuredText (rST) |
|
||||
| Templating | Jinja2 (Rahmenkapitel, Titelseite) |
|
||||
| PDF-Erzeugung | LaTeX (pdflatex/lualatex) |
|
||||
| Versionierung | Git (Gitea auf Hetzner) |
|
||||
| Konfiguration | JSON (ERP-Export) + YAML (Modul-Metadaten) |
|
||||
| CI/Automatisierung | Gitea Actions oder n8n |
|
||||
| Bildkonvertierung | ezdxf → SVG, Pillow (Optimierung) |
|
||||
|
||||
## Repo-Struktur
|
||||
|
||||
### Base-Repo: transport-docs-base
|
||||
|
||||
```
|
||||
transport-docs-base/
|
||||
├── conf_base.py # Sphinx-Basiskonfiguration (wird importiert)
|
||||
├── VERSION # Semver der Dokumentationsbasis
|
||||
├── _ext/
|
||||
│ ├── anlagen_builder.py # Hauptextension: JSON → Buchstruktur
|
||||
│ ├── localized_figure.py # Sprachauflösung für Bilder
|
||||
│ └── glossary_loader.py # CSV → Glossar-Direktive
|
||||
├── _templates/
|
||||
│ ├── latex/
|
||||
│ │ ├── preamble.tex # Firmen-CI: Fonts, Farben, Kopfzeilen
|
||||
│ │ ├── titlepage.tex # Titelseite-Template (Jinja2)
|
||||
│ │ └── maketitle.tex
|
||||
│ └── common/
|
||||
│ └── header_footer.rst
|
||||
├── assets/
|
||||
│ ├── shared/ # Sprachneutrale Bilder (~90%)
|
||||
│ │ ├── photos/
|
||||
│ │ │ ├── weiche_typ_a_foto_01.jpg
|
||||
│ │ │ ├── hubstation_foto_01.jpg
|
||||
│ │ │ └── antrieb_sew_foto_01.jpg
|
||||
│ │ ├── drawings/ # Technische Zeichnungen (DXF → SVG/PDF)
|
||||
│ │ │ ├── weiche_typ_a_layout.svg
|
||||
│ │ │ └── hubstation_schnitt.pdf
|
||||
│ │ ├── symbols/ # ISO 7010 Sicherheitssymbole
|
||||
│ │ │ ├── W001_warnung.svg
|
||||
│ │ │ └── M004_augenschutz.svg
|
||||
│ │ └── diagrams/ # Schaltpläne, Pneumatik
|
||||
│ │ └── stromlaufplan_weiche_a.pdf
|
||||
│ └── localized/ # Sprachspezifische Bilder
|
||||
│ ├── de/
|
||||
│ │ ├── screenshots/
|
||||
│ │ │ └── hmi_hauptmenu.png
|
||||
│ │ └── diagramme/
|
||||
│ │ └── risikograph_weiche_a.svg
|
||||
│ ├── en/
|
||||
│ │ ├── screenshots/
|
||||
│ │ │ └── hmi_hauptmenu.png
|
||||
│ │ └── diagramme/
|
||||
│ │ └── risikograph_weiche_a.svg
|
||||
│ └── fr/
|
||||
│ └── ...
|
||||
├── modules/ # Textbausteine pro Maschinentyp
|
||||
│ ├── weiche_typ_a/
|
||||
│ │ ├── meta.yaml # Abhängigkeiten + Kapitelzuordnung
|
||||
│ │ ├── beschreibung.de.rst
|
||||
│ │ ├── beschreibung.en.rst
|
||||
│ │ ├── risikomatrix.de.rst
|
||||
│ │ ├── risikomatrix.en.rst
|
||||
│ │ ├── wartung.de.rst
|
||||
│ │ └── images/
|
||||
│ │ └── montage_detail_01.jpg
|
||||
│ ├── hubstation/
|
||||
│ │ ├── meta.yaml
|
||||
│ │ ├── beschreibung.de.rst
|
||||
│ │ ├── technische_daten.de.rst
|
||||
│ │ ├── wartung.de.rst
|
||||
│ │ └── images/
|
||||
│ │ └── hubmechanik_detail.jpg
|
||||
│ ├── antrieb_sew/
|
||||
│ │ ├── meta.yaml
|
||||
│ │ └── ...
|
||||
│ └── steuerung_siemens_s7/
|
||||
│ ├── meta.yaml
|
||||
│ └── ...
|
||||
├── chapters/ # Rahmenkapitel (Gerüst)
|
||||
│ ├── 01_einleitung/
|
||||
│ │ ├── template.de.rst # Jinja2-Template mit Platzhaltern
|
||||
│ │ └── template.en.rst
|
||||
│ ├── 02_sicherheit/
|
||||
│ │ ├── allgemein.de.rst # Immer dabei
|
||||
│ │ ├── allgemein.en.rst
|
||||
│ │ ├── normen_ce.de.rst # EU-Konformität
|
||||
│ │ └── normen_ukca.en.rst # UK-spezifisch
|
||||
│ ├── 03_anlagenbeschreibung/
|
||||
│ │ └── template.de.rst # Hier werden Module eingefügt
|
||||
│ ├── 04_betrieb/
|
||||
│ │ └── template.de.rst
|
||||
│ ├── 05_wartung/
|
||||
│ │ ├── allgemein.de.rst
|
||||
│ │ └── schmierplan_template.de.rst
|
||||
│ ├── 06_ersatzteile/
|
||||
│ │ └── template.de.rst
|
||||
│ └── 07_anhang/
|
||||
│ └── template.de.rst
|
||||
├── glossary/
|
||||
│ ├── terms.de.csv # "Begriff;Definition;Kategorie"
|
||||
│ ├── terms.en.csv
|
||||
│ └── terms.fr.csv
|
||||
├── styles/
|
||||
│ ├── firma_logo.pdf
|
||||
│ ├── firma_logo_sw.pdf
|
||||
│ └── color_scheme.yaml # CI-Farben für LaTeX und SVG
|
||||
├── scripts/
|
||||
│ ├── dxf2svg.py # DXF → SVG Konvertierung
|
||||
│ ├── optimize_images.py # Bildoptimierung vor Commit
|
||||
│ └── validate_modules.py # Prüft meta.yaml Konsistenz
|
||||
```
|
||||
|
||||
### Projekt-Repo: projekt-kunde-xyz
|
||||
|
||||
```
|
||||
projekt-kunde-xyz-2026/
|
||||
├── conf.py # Importiert conf_base.py vom Base-Repo
|
||||
├── anlage.json # ERP-Export: Maschinenauswahl + Metadaten
|
||||
├── build.py # Hauptbuild-Skript
|
||||
├── Makefile
|
||||
├── README.md
|
||||
├── images/ # Projektspezifische Bilder
|
||||
│ ├── aufstellplan_halle3.pdf
|
||||
│ ├── foto_abnahme_01.jpg
|
||||
│ └── kundenlogo.pdf
|
||||
├── overrides/ # Projektspezifische Überschreibungen
|
||||
│ ├── modules/
|
||||
│ │ └── weiche_typ_a/
|
||||
│ │ └── beschreibung.de.rst # Überschreibt Basis wenn vorhanden
|
||||
│ └── chapters/
|
||||
│ └── 01_einleitung/
|
||||
│ └── template.de.rst # Kundenspezifische Einleitung
|
||||
├── additional/ # Kapitel die NUR dieses Projekt hat
|
||||
│ ├── sonderausfuehrung_xyz.de.rst
|
||||
│ └── sonderausfuehrung_xyz.en.rst
|
||||
└── transport-docs-base/ ──────────── # Symlink/Mount zum Base-Repo (Share)
|
||||
```
|
||||
### anlage.json (ERP-Export)
|
||||
|
||||
Steuert die Zusammenstellung. Enthält Projektmetadaten, Zielsprachen, Normenregion, Liste verbauter Maschinen und Referenzen auf Zusatzkapitel.
|
||||
@@ -220,3 +377,28 @@ Ausgabe:
|
||||
- `scripts/dxf2svg.py` – DXF → SVG Konvertierung (ezdxf)
|
||||
- `scripts/optimize_images.py` – Bildoptimierung vor Commit (Pillow, max 2000px)
|
||||
- `scripts/validate_modules.py` – Prüft meta.yaml-Konsistenz, fehlende Dateien/Übersetzungen
|
||||
|
||||
## Infrastruktur
|
||||
|
||||
- Hetzner-Server: Gitea (Repos), n8n (CI-Automatisierung), Nextcloud (Dateiablage)
|
||||
- Build-Umgebung: Python 3.11+, Sphinx, LaTeX-Distribution (texlive)
|
||||
- CI: Gitea Actions oder n8n-Webhook → Build → PDF nach Nextcloud
|
||||
|
||||
## Umsetzungsphasen
|
||||
|
||||
| Phase | Beschreibung | Aufwand |
|
||||
|-------|---------------------------------------------------------------|-----------|
|
||||
| 1 | PoC: Ein Modul, ein Kapitel, zwei Sprachen, PDF | 2–3 Tage |
|
||||
| 2 | Base-Repo aufsetzen: Sphinx, Extensions, LaTeX-CI | 3–5 Tage |
|
||||
| 3 | Erste 5–10 Module migrieren, Glossar aufbauen | 1–2 Wochen|
|
||||
| 4 | JSON-Export aus ERP definieren, build.py fertigstellen | 2–3 Tage |
|
||||
| 5 | Pilotprojekt: Erste vollständige Anlagendokumentation | 1 Woche |
|
||||
| 6 | CI/CD: Automatischer Build via Gitea Actions oder n8n | 1–2 Tage |
|
||||
|
||||
## Coding-Konventionen
|
||||
|
||||
- Python: Type Hints, Docstrings, pyright-kompatibel
|
||||
- rST: Eine Datei pro Section, Dateiname = Section-Slug
|
||||
- YAML: 2 Spaces Einrückung, keine Tabs
|
||||
- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`)
|
||||
- Bilder: Dateinamen lowercase, Underscores, beschreibend (`weiche_typ_a_foto_01.jpg`)
|
||||
|
||||
Reference in New Issue
Block a user