196 lines
7.7 KiB
Markdown
196 lines
7.7 KiB
Markdown
# docu_build
|
||
|
||
Sphinx-basiertes Dokumentationssystem fuer Transport- und Hängeförderanlagen. JSON-gesteuerter Build erzeugt aus modularen Textbausteinen mehrsprachige PDF-Dokumentationen (250+ Seiten). Entwickelt von Mista GmbH fuer Schönenberger.
|
||
|
||
Das Projekt befindet sich in der Planungs- und Aufbauphase.
|
||
|
||
## Architektur
|
||
|
||
Das Zielsystem besteht aus zwei Repos:
|
||
|
||
- **transport-docs-base** (dieses Repo): Wiederverwendbare Inhalte -- Sphinx-Extensions (`_ext/`), Module (`modules/`), Kapitelgerüste (`chapters/`), Assets, Glossar, LaTeX-Templates.
|
||
- **projekt-kunde-xyz** (pro Anlage): `anlage.json` (ERP-Export), projektspezifische Bilder, Overrides, `conf.py`, `build.py`. Bindet das Base-Repo per Symlink/Mount ein.
|
||
|
||
### Technologie-Stack
|
||
| Komponente | Technologie |
|
||
|------------------|--------------------------------------------------|
|
||
| Build-System | Sphinx (Python) |
|
||
| Textformat | reStructuredText (rST) und/oder Markdown (MyST) |
|
||
| 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) |
|
||
|
||
|
||
### Build-Pipeline (zu implementieren)
|
||
|
||
```text
|
||
anlage.json → build.py → Versionscheck → Abhängigkeiten auflösen (meta.yaml)
|
||
→ Overrides anwenden → Sphinx-Quellen generieren → sphinx-build -b latex
|
||
→ pdflatex → PDF pro Sprache
|
||
```
|
||
|
||
|
||
## Projektstruktur
|
||
|
||
```text
|
||
docu_build/
|
||
├── _ext/ # Sphinx-Extensions (zu implementieren)
|
||
├── _templates/ # Sphinx/LaTeX-Templates
|
||
├── assets/
|
||
│ ├── shared/ # Sprachunabhängige Bilder/Symbole
|
||
│ └── localized/ # Sprachspezifische Bilder
|
||
├── bin/ # Skripte zur Umgebungsverwaltung
|
||
│ ├── setenv.bat/.sh # Umgebungsvariablen setzen
|
||
│ ├── install_py.bat/.sh # venv erstellen + pip install
|
||
│ ├── activate_venv.bat/.sh # venv aktivieren
|
||
│ ├── get_cmd.bat/.sh # Shell mit Umgebung oeffnen
|
||
│ ├── extract_products.* # Bilder/Text aus Produkt-PDFs extrahieren
|
||
│ └── convert_fortna.* # Fortna-Konvertierung
|
||
├── cfg/ # Konfigurationsdateien
|
||
├── chapters/ # Kapitelgerüste (rST)
|
||
│ ├── 00_inhaltsverzeichnis/
|
||
│ ├── 01_zertifikate/
|
||
│ ├── 02_sicherheit/
|
||
│ ├── 03_anlagenbeschreibung/
|
||
│ ├── 04_betrieb/
|
||
│ ├── 05_wartung/
|
||
│ ├── 06_steuerung/
|
||
│ ├── 07_ersatzteile/
|
||
│ ├── 08_lieferantendoku/
|
||
│ ├── 09_technische_unterlagen/
|
||
│ └── 10_anhang/
|
||
├── data/ # Eingabedaten (nicht im Git)
|
||
├── doc/ # Projektdokumentation
|
||
├── glossary/ # Glossar-Quelldaten (CSV)
|
||
├── lib/ # Python-Bibliotheken
|
||
├── modules/ # Modulbeschreibungen + meta.yaml
|
||
├── scripts/ # Hilfsskripte (dxf2svg, optimize_images, ...)
|
||
├── styles/ # LaTeX-Styles
|
||
├── tests/ # Tests
|
||
├── log/ # Log-Dateien (nicht im Git)
|
||
└── results/ # Build-Ausgaben (nicht im Git)
|
||
```
|
||
|
||
Ein Kundenprojekt enthält nur noch die Verweise auf die verbauten Teile, overrides und additionals, also das Überschreiben von vorhandenen Texten oder Ergänzungen
|
||
|
||
```
|
||
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)
|
||
```
|
||
|
||
Details zur Konfiguration und Aufbau einer Doku siehe [Kernkonzepte](doc/Kernkonzepte.md).
|
||
|
||
### Kapitelstruktur
|
||
|
||
| Kapitel | Inhalt |
|
||
| ------------------------- | --------------------------------------------- |
|
||
| `00_inhaltsverzeichnis` | Wird generiert |
|
||
| `01_zertifikate` | CE/UKCA-Konformität, Konfigurationsbeschreibung, Einbauerklärungen, Komponenten-DoCs |
|
||
| `02_sicherheit` | Sicherheitshinweise, Normen (inkl. gemeinsame/sonstige Spezifikationen), Risikobewertung (inkl. Restrisiken) |
|
||
| `03_anlagenbeschreibung` | Module (via meta.yaml eingefügt) |
|
||
| `04_betrieb` | Betriebsanleitung |
|
||
| `05_wartung` | Wartungsanleitung, Schmierplan |
|
||
| `06_steuerung` | Funktionsbeschreibungen pro Steuerungssystem |
|
||
| `07_ersatzteile` | Ersatzteillisten |
|
||
| `08_lieferantendoku` | Antriebe, Elektrik, Pneumatik, Stahlbau |
|
||
| `09_technische_unterlagen` | Layouts, Schaltpläne, Notstopp |
|
||
| `10_anhang` | Prüfberichte, Abnahmeprotokolle |
|
||
|
||
Details und Begründung der Unterkapitel siehe [Kapitelstruktur](doc/kapitelstruktur.md).
|
||
|
||
### Dateiformat der Textbausteine: rST und Markdown gleichwertig
|
||
|
||
Sphinx liest über die Extension **MyST-Parser** sowohl `.rst`- als auch `.md`-Dateien gleichwertig ein. Beide Formate können projektweit gemischt werden: ein Modul kann `beschreibung.de.rst` verwenden, ein anderes `beschreibung.de.md` – der Build behandelt beide identisch (toctree-Einbindung, Direktiven, Sprachsuffix-Konvention `{name}.{lang}.{rst|md}`). Empfehlung: pro Modul/Kapitel ein einheitliches Format wählen, um Lesbarkeit im Repo zu erhalten; eine Mischung ist aber technisch unproblematisch.
|
||
|
||
## Umgebungsvariablen
|
||
|
||
| Variable | Beschreibung |
|
||
|----------------|---------------------------|
|
||
| `PROJECT` | Wurzelverzeichnis |
|
||
| `PV_BIN` | Skriptverzeichnis |
|
||
| `PV_LIB` | Python-Quellcode |
|
||
| `PV_CFG` | Konfigurationsdateien |
|
||
| `PV_DATA` | Eingabedaten |
|
||
| `PV_LOG` | Log-Dateien |
|
||
| `PV_RESULTS` | Ergebnisse |
|
||
| `PV_EXAMPLES` | Beispieldateien |
|
||
| `PYTHONPATH` | Erweitert um `PV_LIB` |
|
||
|
||
## Installation
|
||
|
||
### Voraussetzungen
|
||
|
||
- Python 3.10 oder hoeher
|
||
|
||
### Setup (Windows)
|
||
|
||
```bat
|
||
bin\install_py.bat
|
||
```
|
||
|
||
### Setup (Linux / macOS)
|
||
|
||
```bash
|
||
bash bin/install_py.sh
|
||
```
|
||
|
||
## Nutzung
|
||
|
||
### Umgebung aktivieren
|
||
|
||
```bat
|
||
bin\activate_venv.bat # Windows
|
||
```
|
||
|
||
```bash
|
||
source bin/activate_venv.sh # Linux / macOS
|
||
```
|
||
|
||
### Shell mit gesetzten Variablen oeffnen
|
||
|
||
```bat
|
||
bin\get_cmd.bat # Windows
|
||
```
|
||
|
||
```bash
|
||
source bin/get_cmd.sh # Linux / macOS
|
||
```
|
||
|
||
### Produkt-PDFs extrahieren
|
||
|
||
Extrahiert Bilder und Text (als rST) aus den PDFs in `data/Produktprogramm/`:
|
||
|
||
```bat
|
||
bin\extract_products.bat # Windows
|
||
```
|
||
|
||
## Lizenz
|
||
|
||
MIT License -- siehe [LICENSE](LICENSE)
|
||
|
||
## Autor
|
||
|
||
Michael Stangl (GitHub: mistamichael)
|