diff --git a/CLAUDE.md b/CLAUDE.md index 294294a..eb687ea 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,7 +36,7 @@ Dieses Repo (`docu_build`) dient als Entwicklungs- und Planungsumgebung. Das Zie | Komponente | Technologie | |------------------|--------------------------------------------------| | Build-System | Sphinx (Python) | -| Textformat | reStructuredText (rST) | +| Textformat | reStructuredText (rST) und/oder Markdown (MyST) | | Templating | Jinja2 (Rahmenkapitel, Titelseite) | | PDF-Erzeugung | LaTeX (pdflatex/lualatex) | | Versionierung | Git (Gitea auf Hetzner) | @@ -53,7 +53,9 @@ Dieses Repo (`docu_build`) dient als Entwicklungs- und Planungsumgebung. Das Zie **Override-Reihenfolge**: `projekt/overrides/` > `transport-docs-base/modules/` bzw. `chapters/` -**Mehrsprachigkeit**: Dateinamenskonvention `{name}.{lang}.rst`, Fallback auf `de`. Bilder via `localized-figure`-Direktive (`assets/localized/{lang}/`). Glossar aus `terms.{lang}.csv` (Semikolon-getrennt). +**Mehrsprachigkeit**: Dateinamenskonvention `{name}.{lang}.{rst|md}`, Fallback auf `de`. Bilder via `localized-figure`-Direktive (`assets/localized/{lang}/`). Glossar aus `terms.{lang}.csv` (Semikolon-getrennt). + +**rST/Markdown-Mischbetrieb**: Sphinx liest über die Extension MyST-Parser `.rst`- und `.md`-Dateien gleichwertig ein. Beide Formate können projektweit gemischt werden (z. B. `beschreibung.de.rst` neben `wartung.de.md` im selben Modul) – toctree-Einbindung, Direktiven und die Sprachsuffix-Konvention funktionieren identisch. Pro Modul/Kapitel wird ein einheitliches Format empfohlen, ein Mix ist aber technisch unproblematisch. **anlage.json**: Steuert Zusammenstellung – enthält `projekt` (Metadaten, Sprachen, Normenregion), `maschinen` (Modulliste mit Positionen/Varianten/Optionen), `zusatz_kapitel`. @@ -65,8 +67,10 @@ Details siehe `doc/Kernkonzepte.md`. ```text 00_inhaltsverzeichnis – Inhaltsverzeichnis (wird generiert) -01_zertifikate – CE/UKCA-Konformität, Konfigurationsbeschreibung -02_sicherheit – Allgemein, Normen, Risikobewertung +01_zertifikate – CE/UKCA-Konformität, Konfigurationsbeschreibung, + Einbauerklärungen, Komponenten-Konformitätserklärungen +02_sicherheit – Allgemein, Normen (inkl. gemeinsame/sonstige Spezifikationen), + Risikobewertung (inkl. Restrisiken) 03_anlagenbeschreibung – Module werden hier via meta.yaml eingefügt 04_betrieb – Betriebsanleitung 05_wartung – Wartungsanleitung, Schmierplan @@ -77,6 +81,8 @@ Details siehe `doc/Kernkonzepte.md`. 10_anhang – Prüfberichte, Abnahmeprotokolle ``` +Kapitel `01_zertifikate` und `02_sicherheit` wurden um Unterkapitel ergänzt, die von Anhang IV Teil A der VO (EU) 2023/1230 (neue Maschinenverordnung, ersetzt Anhang VII MRL 2006/42/EG) gefordert werden: Einbauerklärungen/Montageanleitungen für eingebaute unvollständige Maschinen, Konformitätserklärungen zugekaufter Komponenten, gemeinsame Spezifikationen, sonstige technische Spezifikationen sowie eine explizite Restrisiken-Section. + Details siehe `doc/kapitelstruktur.md`. ### Sphinx-Extensions (zu implementieren in `_ext/`) diff --git a/README.md b/README.md index 859b33c..9194328 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Das Zielsystem besteht aus zwei Repos: | Komponente | Technologie | |------------------|--------------------------------------------------| | Build-System | Sphinx (Python) | -| Textformat | reStructuredText (rST) | +| Textformat | reStructuredText (rST) und/oder Markdown (MyST) | | Templating | Jinja2 (Rahmenkapitel, Titelseite) | | PDF-Erzeugung | LaTeX (pdflatex/lualatex) | | Versionierung | Git (Gitea auf Hetzner) | @@ -107,8 +107,8 @@ Details zur Konfiguration und Aufbau einer Doku siehe [Kernkonzepte](doc/Kernko | Kapitel | Inhalt | | ------------------------- | --------------------------------------------- | | `00_inhaltsverzeichnis` | Wird generiert | -| `01_zertifikate` | CE/UKCA-Konformität, Konfigurationsbeschreibung | -| `02_sicherheit` | Sicherheitshinweise, Normen, Risikobewertung | +| `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 | @@ -118,6 +118,12 @@ Details zur Konfiguration und Aufbau einer Doku siehe [Kernkonzepte](doc/Kernko | `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 | diff --git a/doc/Kernkonzepte.md b/doc/Kernkonzepte.md index 4cb9354..7cf5cb2 100644 --- a/doc/Kernkonzepte.md +++ b/doc/Kernkonzepte.md @@ -21,7 +21,7 @@ Umsetzung: Mista GmbH | Komponente | Technologie | |------------------|--------------------------------------------------| | Build-System | Sphinx (Python) | -| Textformat | reStructuredText (rST) | +| Textformat | reStructuredText (rST) und/oder Markdown (MyST) | | Templating | Jinja2 (Rahmenkapitel, Titelseite) | | PDF-Erzeugung | LaTeX (pdflatex/lualatex) | | Versionierung | Git (Gitea auf Hetzner) | @@ -102,11 +102,19 @@ transport-docs-base/ │ ├── 01_einleitung/ │ │ ├── template.de.rst # Jinja2-Template mit Platzhaltern │ │ └── template.en.rst +│ ├── 01_zertifikate/ +│ │ ├── konformitaetserklaerung/ +│ │ ├── konfigurationsbeschreibung/ +│ │ ├── einbauerklaerungen/ # Einbauerklärung + Montageanleitung unvollständiger Maschinen +│ │ └── konformitaetserklaerungen_komponenten/ # DoCs zugekaufter Komponenten │ ├── 02_sicherheit/ │ │ ├── allgemein.de.rst # Immer dabei │ │ ├── allgemein.en.rst │ │ ├── normen_ce.de.rst # EU-Konformität -│ │ └── normen_ukca.en.rst # UK-spezifisch +│ │ ├── normen_ukca.en.rst # UK-spezifisch +│ │ ├── normen/gemeinsame_spezifikationen/ # "gemeinsame Spezifikationen" (VO (EU) 2023/1230, Art. 20) +│ │ ├── normen/sonstige_spezifikationen/ # sonstige angewandte techn. Spezifikationen +│ │ └── risikobewertung/restrisiken/ # explizite Restrisiken-Section │ ├── 03_anlagenbeschreibung/ │ │ └── template.de.rst # Hier werden Module eingefügt │ ├── 04_betrieb/ @@ -241,6 +249,8 @@ requires: - antrieb_sew ``` +Module können in `02_sicherheit` neben `risikomatrix` optional auch die Section `restrisiken` referenzieren, um modulspezifische Restrisiken gemäß Anhang IV Teil A VO (EU) 2023/1230 auszuweisen. Einbauerklärungen und Komponenten-Konformitätserklärungen (`01_zertifikate/einbauerklaerungen/`, `01_zertifikate/konformitaetserklaerungen_komponenten/`) sind i. d. R. keine Modul-Sections, sondern projekt-/lieferantenweite Dokumente und werden direkt im Projekt-Repo (`overrides/` bzw. `additional/`) oder in `08_lieferantendoku` abgelegt und von dort referenziert. + ### conf.py (Projekt-Konfiguration) Importiert die Basiskonfiguration vom gemounteten Base-Repo und setzt projektspezifische Overrides. @@ -316,7 +326,7 @@ Base-Repo hat Semver in `VERSION`. Projekt-Repo kann `"base_version": ">=2.1.0"` ### Drei Ebenen -1. **Textbausteine**: Dateinamenskonvention `{name}.{lang}.rst`. Fallback auf `de` bei fehlender Übersetzung. +1. **Textbausteine**: Dateinamenskonvention `{name}.{lang}.{rst|md}`. 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. @@ -324,6 +334,10 @@ Base-Repo hat Semver in `VERSION`. Projekt-Repo kann `"base_version": ">=2.1.0"` 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. +### rST und Markdown gleichwertig (MyST) + +Sphinx liest über die Extension **MyST-Parser** `.rst`- und `.md`-Dateien gleichwertig ein. Beide Dateiformate können projektweit gemischt bzw. gleichwertig verwendet werden – z. B. `beschreibung.de.rst` in einem Modul und `wartung.de.md` in einem anderen, oder auch innerhalb desselben Moduls. Toctree-Einbindung, Sphinx-Direktiven (in MyST via ```` ```{direktive} ```` -Syntax) und die Sprachsuffix-Konvention `{name}.{lang}.{rst|md}` funktionieren für beide Formate identisch. Voraussetzung ist `myst-parser` als Sphinx-Extension in `conf_base.py`. Empfehlung: pro Modul/Kapitel ein einheitliches Format wählen, um die Lesbarkeit im Repo zu erhalten – eine Mischung ist aber technisch unproblematisch und erzwingt keine Migration bestehender rST-Bausteine. + ## Bildverwaltung | Kategorie | Pfad | Beispiele | diff --git a/doc/kapitelstruktur.md b/doc/kapitelstruktur.md index de24a1d..15506ed 100644 --- a/doc/kapitelstruktur.md +++ b/doc/kapitelstruktur.md @@ -8,7 +8,7 @@ Angepasst auf deutsche Ordnernamen, Sprachtrennung auf Top-Level. | Nr | Ordner | Inhalt | Fortna-Quelle | |----|--------|--------|---------------| | 00 | `00_inhaltsverzeichnis` | Inhaltsverzeichnis, Dokumentennotizen | 00_CONTENTS_NOTES | -| 01 | `01_zertifikate` | CE/UKCA-Konformitaetserklaerungen, Konfigurationsbeschreibung | 01_CERTIFICATES | +| 01 | `01_zertifikate` | CE/UKCA-Konformitaetserklaerungen, Konfigurationsbeschreibung, Einbauerklaerungen, Komponenten-DoCs | 01_CERTIFICATES | | 02 | `02_sicherheit` | Allgemeine Sicherheit, Normen, Risikobewertung | (neu, teilweise 04_TECHNICAL_DOC) | | 03 | `03_anlagenbeschreibung` | Maschinenmodule (via meta.yaml eingefuegt) | (neu) | | 04 | `04_betrieb` | Betriebsanleitung | 02_INSTRUCTIONS (Betriebsanleitung) | @@ -29,23 +29,34 @@ Wird vom Build-Prozess generiert. Enthaelt Gesamtinhaltsverzeichnis und ggf. Dok ```text 01_zertifikate/ - konformitaetserklaerung/ # CE-/UKCA-Erklaerungen (Fortna: 01_SCHOENENBERGER) - konfigurationsbeschreibung/ # Konfigurationsbeschreibung fuer CE (Fortna: 02_KONFIGURATIONSBESCHREIBUNG) + konformitaetserklaerung/ # CE-/UKCA-Erklaerungen (Fortna: 01_SCHOENENBERGER) + konfigurationsbeschreibung/ # Konfigurationsbeschreibung fuer CE (Fortna: 02_KONFIGURATIONSBESCHREIBUNG) + einbauerklaerungen/ # NEU: Einbauerklaerungen + Montageanleitungen fuer eingebaute unvollstaendige Maschinen + konformitaetserklaerungen_komponenten/ # NEU: Sammlung der DoCs zugekaufter Komponenten (Querverweis auf 08_lieferantendoku) ``` Fortna-Beispieldokumente: - EC Declaration of Conformity_V2_EN.pdf - Konfigurationsbeschreibung_fuer_CE_V2.pdf +**Ergaenzung nach Anhang IV, Teil A, VO (EU) 2023/1230:** Die neuen Unterordner `einbauerklaerungen/` und `konformitaetserklaerungen_komponenten/` decken zwei Pflichtangaben ab, die im bisherigen Kapitelzuschnitt keinen festen Platz hatten: +- Einbauerklaerung + Montageanleitung fuer eingebaute unvollstaendige Maschinen (z. B. zugekaufte Antriebe/Steuerungen, die selbst als unvollstaendige Maschine geliefert werden) +- Konformitaetserklaerungen zugekaufter Komponenten – bisher nur implizit verstreut in `08_lieferantendoku/*` (nach Gewerk sortiert, nicht nach Dokumenttyp) + ### 02_sicherheit ```text 02_sicherheit/ - allgemein/ # Allgemeine Sicherheitshinweise - normen/ # CE (EU), UKCA (UK) - je nach normen_region in anlage.json - risikobewertung/ # Risikomatrizen, Gefahrenanalysen + allgemein/ # Allgemeine Sicherheitshinweise + normen/ # Harmonisierte Normen, CE (EU), UKCA (UK) - je nach normen_region in anlage.json + gemeinsame_spezifikationen/ # NEU: "gemeinsame Spezifikationen" (Begriff aus VO (EU) 2023/1230, Art. 20) + sonstige_spezifikationen/ # NEU: sonstige angewandte techn. Spezifikationen, falls keine harmonisierte Norm existiert + risikobewertung/ # Risikomatrizen, Gefahrenanalysen + restrisiken/ # NEU: explizite Restrisiken-Section (bisher nur implizit in der Risikomatrix) ``` +**Ergaenzung nach Anhang IV, Teil A:** Anhang IV verlangt explizit die Referenzen der angewandten harmonisierten Normen *oder gemeinsamen Spezifikationen* (bei Teilanwendung mit Angabe der verwendeten Teile), sowie – falls keine harmonisierten Normen angewandt wurden – die sonstigen angewandten technischen Spezifikationen. Bisher gab es dafuer nur den allgemeinen Ordner `normen/`. Ebenso verlangt Anhang IV eine Beschreibung der Restrisiken als Teil der Risikobeurteilungsunterlagen – dafuer bisher keine eigene Section, nur implizit in der Risikomatrix enthalten. + ### 03_anlagenbeschreibung Keine feste Unterstruktur - Module werden hier durch den Build-Prozess via meta.yaml eingefuegt. Jedes Modul liefert seine Beschreibung, technische Daten etc. @@ -253,4 +264,23 @@ Unterschriebene Validierungsprotokolle, bestehend aus: - [ ] Wie läuft die Ersatzteilfindung nach der Dokumentation statt? - [ ] Wie die Behandlung einer Anlage bei Fehler oder Störungen? - [ ] Welche Daten des Produktprogrammes sollen in die Dokumentation eingang finden? -- [ ] Welche Abteilung liefert normalerweise was in der Dokumentation (Liste Automation ist vorhanden, Was passiert bei Sonderkonstruktionen)? \ No newline at end of file +- [ ] Welche Abteilung liefert normalerweise was in der Dokumentation (Liste Automation ist vorhanden, Was passiert bei Sonderkonstruktionen)? +- [ ] Soll die Rechtsgrundlage (MRL 2006/42/EG vs. VO (EU) 2023/1230) als Feld in `anlage.json` gefuehrt werden (analog zu `normen_region`), damit Textbausteine und Kapitelverweise projektspezifisch zwischen "Anhang I MRL" und "Anhang III/IV MVO" umschalten koennen? Relevant spaetestens ab Pflichtanwendung der MVO am 20.01.2027; Altprojekte (z. B. Fortna) bleiben MRL-referenziert. + +## Ergaenzungsbedarf durch VO (EU) 2023/1230, Anhang IV Teil A + +Anhang IV Teil A ersetzt Anhang VII der MRL 2006/42/EG und listet die Mindestinhalte der technischen Unterlagen fuer vollstaendige Maschinen. Abgleich mit der bestehenden Kapitelstruktur (Details siehe Abschnitte `01_zertifikate` und `02_sicherheit` oben): + +| Anhang IV Teil A – Anforderung | Bereits abgedeckt durch | Ergaenzungsbedarf | +|---|---|---| +| Beschreibung der Maschine + bestimmungsgemaesse Verwendung | `03_anlagenbeschreibung` | Bestimmungsgemaesse Verwendung als Pflichtabschnitt je Modul sicherstellen | +| Risikobeurteilungsunterlagen inkl. GSGA-Liste, Schutzmassnahmen, Restrisiken | `02_sicherheit/risikobewertung` | Restrisiken als eigene Section (`restrisiken/`, s. o.) | +| Entwurfs-/Fertigungszeichnungen, Plaene | `09_technische_unterlagen/layouts`, `schaltplaene` | keiner | +| Erlaeuterungen zu Zeichnungen/Funktionsweise | `06_steuerung/*` | fuer rein mechanische Baugruppen ohne Steuerung ggf. in `03_anlagenbeschreibung` ergaenzen | +| Referenzen harmonisierter Normen/gemeinsamer Spezifikationen | `02_sicherheit/normen` | Unterordner `gemeinsame_spezifikationen/` (s. o.) | +| Sonstige angewandte technische Spezifikationen | – | Unterordner `sonstige_spezifikationen/` (s. o.) | +| Pruefberichte | `10_anhang/pruefberichte` | keiner | +| Exemplar der Betriebsanleitung | `04_betrieb/betriebsanleitung` | keiner | +| Einbauerklaerung + Montageanleitung fuer eingebaute unvollstaendige Maschinen | – | Neuer Ordner `01_zertifikate/einbauerklaerungen/` (s. o.) | +| Konformitaetserklaerungen zugekaufter Komponenten | bisher verstreut in `08_lieferantendoku/*` | Neuer Ordner `01_zertifikate/konformitaetserklaerungen_komponenten/` (s. o.) | +| Kopie der eigenen EU-Konformitaetserklaerung | `01_zertifikate/konformitaetserklaerung` | Ordner existiert, aktuell nur Platzhalter (`.gitkeep`) – inhaltlich zu befuellen | \ No newline at end of file diff --git a/examples/Fortna/KA135776 FortnaHM20260416 NST.xlsx b/examples/Fortna/KA135776 FortnaHM20260416 NST.xlsx deleted file mode 100644 index ccb862b..0000000 Binary files a/examples/Fortna/KA135776 FortnaHM20260416 NST.xlsx and /dev/null differ