Hilfskripte zum Extrakt aus dem Produktprogramm erstellt. Kernkonzepte in README.md und doc
This commit is contained in:
@@ -0,0 +1,222 @@
|
||||
# Kernkonzepte
|
||||
|
||||
### anlage.json (ERP-Export)
|
||||
|
||||
Steuert die Zusammenstellung. Enthält Projektmetadaten, Zielsprachen, Normenregion, Liste verbauter Maschinen und Referenzen auf Zusatzkapitel.
|
||||
|
||||
**Beispiel:**
|
||||
|
||||
```json
|
||||
{
|
||||
"projekt": {
|
||||
"nummer": "P-2026-0042",
|
||||
"kunde": "Müller Automotive GmbH",
|
||||
"kunde_logo": "images/kundenlogo.pdf",
|
||||
"standort": "Werk Ingolstadt, Halle 3",
|
||||
"sprachen": ["de", "en"],
|
||||
"normen_region": "EU",
|
||||
"base_version": ">=1.0.0"
|
||||
},
|
||||
"maschinen": [
|
||||
{
|
||||
"modul": "weiche_typ_a",
|
||||
"anzahl": 4,
|
||||
"positionen": ["W01", "W02", "W03", "W04"],
|
||||
"variante": "standard"
|
||||
},
|
||||
{
|
||||
"modul": "hubstation",
|
||||
"anzahl": 2,
|
||||
"positionen": ["H01", "H02"],
|
||||
"variante": "schwerlast",
|
||||
"optionen": ["hydraulisch"]
|
||||
},
|
||||
{
|
||||
"modul": "antrieb_sew",
|
||||
"anzahl": 12,
|
||||
"positionen": ["A01-A12"]
|
||||
},
|
||||
{
|
||||
"modul": "steuerung_siemens_s7",
|
||||
"anzahl": 1,
|
||||
"positionen": ["SPS01"],
|
||||
"optionen": ["profinet", "hmi_tp700"]
|
||||
}
|
||||
],
|
||||
"zusatz_kapitel": [
|
||||
"additional/sonderausfuehrung_xyz"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### meta.yaml (Modul-Metadaten)
|
||||
|
||||
Pro Maschinentyp-Modul. Definiert Bezeichner, mehrsprachigen Namen, Kapitelzuordnung, Bildreferenzen und Abhängigkeiten.
|
||||
|
||||
**Beispiel** (`modules/weiche_typ_a/meta.yaml`):
|
||||
|
||||
```yaml
|
||||
module: weiche_typ_a
|
||||
display_name:
|
||||
de: "Weiche Typ A"
|
||||
en: "Switch Type A"
|
||||
|
||||
chapters:
|
||||
- 02_sicherheit:
|
||||
sections: [risikomatrix]
|
||||
- 03_anlagenbeschreibung:
|
||||
sections: [beschreibung, technische_daten]
|
||||
- 05_wartung:
|
||||
sections: [wartung, schmierplan]
|
||||
|
||||
images:
|
||||
shared:
|
||||
- photos/weiche_typ_a_foto_01.jpg
|
||||
- drawings/weiche_typ_a_layout.svg
|
||||
- diagrams/stromlaufplan_weiche_a.pdf
|
||||
localized:
|
||||
- diagramme/risikograph_weiche_a.svg
|
||||
- screenshots/hmi_hauptmenu.png
|
||||
module_local:
|
||||
- montage_detail_01.jpg
|
||||
|
||||
requires:
|
||||
- antrieb_sew
|
||||
```
|
||||
|
||||
### conf.py (Projekt-Konfiguration)
|
||||
|
||||
Importiert die Basiskonfiguration vom gemounteten Base-Repo und setzt projektspezifische Overrides.
|
||||
|
||||
**Beispiel** (`projekt-kunde-xyz-2026/conf.py`):
|
||||
|
||||
```python
|
||||
import sys
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
# ══ Pfad zum Base-Repo (Share/Mount) ══
|
||||
BASE_DOCS = Path(os.environ.get(
|
||||
"DOCS_BASE_PATH",
|
||||
Path(__file__).parent / "transport-docs-base"
|
||||
))
|
||||
|
||||
# Extensions und Basiskonfiguration importieren
|
||||
sys.path.insert(0, str(BASE_DOCS / "_ext"))
|
||||
sys.path.insert(0, str(BASE_DOCS))
|
||||
from conf_base import * # noqa: F401, F403
|
||||
|
||||
# ══ Projektspezifische Overrides ══
|
||||
project = "Anlagendokumentation P-2026-0042"
|
||||
release = "1.0"
|
||||
author = "Mista GmbH"
|
||||
copyright = "2026, Mista GmbH"
|
||||
|
||||
# Bildpfade: Projekt → Overrides → Base (Reihenfolge = Priorität)
|
||||
image_search_path = [
|
||||
"images", # Projektbilder
|
||||
"overrides", # Überschreibungen
|
||||
str(BASE_DOCS / "assets" / "shared"), # Sprachneutrale Basis
|
||||
str(BASE_DOCS / "assets" / "localized"), # Sprachspezifische Basis
|
||||
str(BASE_DOCS / "modules"), # Modulbilder
|
||||
]
|
||||
|
||||
# Sphinx-Extensions aus Base-Repo laden
|
||||
extensions += [
|
||||
"anlagen_builder",
|
||||
"localized_figure",
|
||||
"glossary_loader",
|
||||
]
|
||||
|
||||
# Glossar-Pfad
|
||||
glossary_csv_path = str(BASE_DOCS / "glossary")
|
||||
|
||||
# LaTeX-Templates aus Base-Repo
|
||||
templates_path.insert(0, str(BASE_DOCS / "_templates"))
|
||||
|
||||
# LaTeX-spezifisch
|
||||
latex_elements = {
|
||||
"preamble": open(BASE_DOCS / "_templates" / "latex" / "preamble.tex").read(),
|
||||
"maketitle": open(BASE_DOCS / "_templates" / "latex" / "maketitle.tex").read(),
|
||||
"papersize": "a4paper",
|
||||
"pointsize": "11pt",
|
||||
}
|
||||
```
|
||||
|
||||
### Override-Mechanismus
|
||||
|
||||
Suchreihenfolge beim Build:
|
||||
1. `projekt/overrides/` (projektspezifisch)
|
||||
2. `transport-docs-base/modules/` bzw. `chapters/` (allgemein)
|
||||
|
||||
Ermöglicht kundenspezifische Anpassungen ohne Base-Repo-Änderung.
|
||||
|
||||
### Versionskontrolle
|
||||
|
||||
Base-Repo hat Semver in `VERSION`. Projekt-Repo kann `"base_version": ">=2.1.0"` in anlage.json setzen. build.py prüft Kompatibilität vor dem Build.
|
||||
|
||||
## Mehrsprachigkeit
|
||||
|
||||
### Drei Ebenen
|
||||
|
||||
1. **Textbausteine**: Dateinamenskonvention `{name}.{lang}.rst`. Fallback auf `de` bei fehlender Übersetzung.
|
||||
2. **Bilder**: `localized-figure`-Direktive löst `assets/localized/{lang}/pfad/bild.png` auf. Fallback auf `de`. Optional: Jinja2-SVG-Templates für Diagramme mit Text.
|
||||
3. **Glossar**: CSV pro Sprache (`terms.{lang}.csv`), `glossary_loader.py` erzeugt Sphinx-Glossardirektiven. Im Text via `:term:`Fachbegriff`` verlinkt.
|
||||
|
||||
### Sprachspezifische Normen
|
||||
|
||||
Gesteuert über `normen_region` in anlage.json. Kapitel 02_sicherheit enthält z.B. `normen_ce.de.rst` (EU) und `normen_ukca.en.rst` (UK), Build wählt nach Region.
|
||||
|
||||
## Bildverwaltung
|
||||
|
||||
| Kategorie | Pfad | Beispiele |
|
||||
|------------------|-----------------------------------|----------------------------------------------|
|
||||
| Sprachneutral | `assets/shared/{typ}/` | Fotos, DXF/SVG-Zeichnungen, ISO-Symbole |
|
||||
| Sprachspezifisch | `assets/localized/{lang}/{typ}/` | HMI-Screenshots, Risikographen, Typenschilder|
|
||||
| Modulspezifisch | `modules/{modul}/images/` | Montagedetails |
|
||||
| Projektspezifisch| `projekt/images/` | Aufstellpläne, Abnahmefotos, Kundenlogo |
|
||||
|
||||
Formate: SVG/PDF für Zeichnungen (vektoriell), JPG für Fotos (max 2000px, 85% Qualität).
|
||||
|
||||
## Build-Prozess
|
||||
|
||||
```
|
||||
anlage.json ──→ build.py
|
||||
│
|
||||
├─ Phase 1: Konfiguration einlesen, Versionscheck
|
||||
├─ Phase 2: Abhängigkeiten auflösen (meta.yaml, transitiv)
|
||||
│ Overrides anwenden (Projekt > Base)
|
||||
│ Fehlende Module/Bilder/Übersetzungen melden
|
||||
├─ Phase 3: Sphinx-Quellen generieren (index.rst, toctrees)
|
||||
│ Glossar aus CSV erzeugen
|
||||
│ Jinja2-Templates mit Projektdaten füllen
|
||||
└─ Phase 4: sphinx-build -b latex → pdflatex → PDF (pro Sprache)
|
||||
|
||||
Ausgabe:
|
||||
_output/P-2026-0042_Dokumentation_DE.pdf
|
||||
_output/P-2026-0042_Documentation_EN.pdf
|
||||
```
|
||||
|
||||
## Sphinx-Extensions (zu implementieren)
|
||||
|
||||
### anlagen_builder.py
|
||||
- Liest anlage.json + meta.yaml aller referenzierten Module
|
||||
- Löst Abhängigkeiten auf (topologisch, transitiv)
|
||||
- Generiert toctree-Einträge pro Kapitel
|
||||
- Wendet Override-Logik an
|
||||
|
||||
### localized_figure.py
|
||||
- Neue Direktive `.. localized-figure::`
|
||||
- Löst Bildpfad nach Build-Sprache auf
|
||||
- Fallback: `de` wenn Sprachversion fehlt
|
||||
|
||||
### glossary_loader.py
|
||||
- Liest `terms.{lang}.csv` (Semikolon-getrennt)
|
||||
- Erzeugt `.. glossary::` Blöcke
|
||||
- Ermöglicht `:term:` Verlinkung im gesamten Dokument
|
||||
|
||||
## Hilfsskripte
|
||||
|
||||
- `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
|
||||
Reference in New Issue
Block a user