Dokumentation mit MkDocs¶

Dieses Projekt verwendet MkDocs mit dem Material Theme für strukturierte Engineering-Dokumentation. Schreibe Seiten in Markdown, halte Quelldateien unter docs/, und aktualisiere mkdocs.yml, wenn eine Seite in der Navigation erscheinen soll.

Lokale Befehle¶

Aus dem Repository-Root ausführen:

pcs init
pcs docs serve
pcs docs open
pcs docs render
pcs docs build

Verwende pcs docs serve während der Bearbeitung und pcs docs open, um die lokale Seite im Standardbrowser zu öffnen. Verwende pcs docs render nach Änderungen an PlantUML-Diagrammen. Verwende pcs docs build vor Veröffentlichung oder Commit größerer Dokumentationsänderungen. pcs init erstellt die virtuelle Umgebung und installiert die gepinnten Dokumentationspakete.

Überschriften und Text¶

Verwende Überschriften, um eine klare Seitenstruktur zu erzeugen. MkDocs baut das Inhaltsverzeichnis der Seite aus den Überschriften.

# Page Title

## Main Section

### Detail Section

Bevorzuge kurze Absätze und direkte Formulierungen. Verwende Inline-Code für PLC-Symbole, Dateinamen, Befehle und Konfigurationsschlüssel wie pcs.config.json, FB_CellDemo oder xuiSignalRange.

Listen¶

Verwende ungeordnete Listen für zusammengehörige Punkte:

PLC-Quelldateien liegen in tia/exports.
PLC-Quelldateien sind nach Subsystem gruppiert; .scl-, .db- und .udt-Dateien liegen zusammen.
Deployment-Ziele werden in pcs.config.json konfiguriert.

Verwende nummerierte Listen für Prozeduren:

Quelldatei bearbeiten.
Nach TIA Portal deployen.
PLC-Software kompilieren.
Compiler-Meldungen prüfen.

Tabellen¶

Tabellen sind nützlich für Parameter, Signalzuordnungen und Statusbeschreibungen.

Signal	Typ	Beschreibung
`xinRawValue`	`Int`	Roher analoger Eingangswert vom Modul
`xuiSignalRange`	`USInt`	Rohwertbereich: unipolar, live-zero oder bipolar
`yrePhysValue`	`Real`	Skalierter Engineering-Wert
`yboFault`	`Bool`	Sammelstörmeldung

Admonitions¶

Verwende Admonitions für Informationen, die hervorstechen müssen.

Warning

Shutdown sequence must complete before restart.

Note

Verwende Notes für hilfreichen Kontext, der nicht Teil der Hauptprozedur ist.

Tip

Halte wiederverwendbare Befehlsbeispiele in fenced code blocks, damit sie sicher kopiert werden können.

Danger

Verwende Danger nur für Aktionen, die Equipment beschädigen, unsichere Zustände erzeugen oder Daten zerstören können.

Einklappbare Details¶

Verwende einklappbare Abschnitte, wenn Details nützlich sind, aber nicht bei jedem Lesen benötigt werden.

Details

Erweiterte Informationen

Dies ist ein guter Ort für Hintergrund, alternative Befehle oder Implementierungsnotizen.

Standardmäßig geöffnet

Füge ein + nach den Fragezeichen hinzu, wenn der Abschnitt standardmäßig geöffnet sein soll.

Tabs¶

Tabs sind nützlich, wenn dasselbe Thema PLC-, HMI-, Simulations- und Commissioning-Sichten hat.

PLCHMIInbetriebnahme

PLC Beschreibung

"FC_AnalogInputScale"(
    xinRawValue := "DB_Motors"._uTemperature.xinRawValue,
    xuiSignalRange := "DB_Motors"._uTemperature.xuiSignalRange
);

HMI Beschreibung

Zeige hier bedienerorientierte Labels, Alarme und Statusfelder.

Verwende diesen Tab für Prüfungen, erwartete Werte und Troubleshooting-Hinweise.

Codeblöcke¶

Verwende fenced code blocks mit einem Sprachnamen.

.\tools\tia-openness\deploy.ps1 `
  -Project "%USERPROFILE%\Documents\TIA-Projekte\PCS\PCS.ap20" `
  -Plc "PLC_1"

REGION S001 - Input parameter validation
    // Validate range selection and scaling parameters.
END_REGION

Links¶

Verwende relative Links für Seiten innerhalb der Dokumentation:

Verwende normale Markdown-Links für externe Referenzen:

[MkDocs](https://www.mkdocs.org/)

Bilder und Diagramme¶

Speichere PlantUML-Source und gerenderte SVG-Dateien möglichst nebeneinander.

docs/development/diagrams/deployment-workflow.puml
docs/development/diagrams/deployment-workflow.svg

Referenziere gerenderte SVGs aus Markdown:

![Deployment workflow](diagrams/deployment-workflow.svg)

MkDocs rendert .puml-Dateien im aktuellen Setup nicht automatisch. Rendere Diagramme aus dem Repository-Root, bevor du die Docs baust:

pcs docs render
pcs docs build

pcs docs build fragt, ob Diagramme zuerst gerendert werden sollen. Beantworte bei Dokumentationsänderungen mit PlantUML-Änderungen mit Y oder führe pcs docs render explizit vor dem Build aus.

Mathematik¶

Inline-Mathematik kann als \( y = mx + b \) geschrieben werden.

Block-Mathematik:

\[
y = y_{min} + \frac{x - x_{min}}{x_{max} - x_{min}} \cdot (y_{max} - y_{min})
\]

Gerendert:

\[ y = y_{min} + \frac{x - x_{min}}{x_{max} - x_{min}} \cdot (y_{max} - y_{min}) \]

Nützliche Muster¶

Verwende Parametertabellen für PLC-Bausteine:

Parameter	Richtung	Typ	Bedeutung
`xinRawValue`	Input	`Int`	Roher Kanalwert
`xrePhysMin`	Input	`Real`	Physikalischer Wert beim minimalen Signal
`xrePhysMax`	Input	`Real`	Physikalischer Wert beim maximalen Signal
`yboValid`	Output	`Bool`	Skalierter Wert kann verwendet werden

Verwende Statustabellen für Diagnosen:

Status	Bedeutung	Bedieneraktion
`yboWireBreak`	Live-zero-Signal unterhalb des gültigen Bereichs oder Hardwarediagnose aktiv	Verdrahtung und Transmitter prüfen
`yboOverflow`	Rohwert oberhalb der Modulrepräsentation	Kanalkonfiguration und Signal prüfen
`yboUnderflow`	Rohwert unterhalb der Modulrepräsentation	Kanalkonfiguration und Signal prüfen
`yboRangeError`	Rohwert außerhalb des nominal konfigurierten Bereichs	Sensor und Prozesszustand prüfen

Verwende Tabs, wenn ein Thema mehrere Zielgruppen hat, und einklappbare Details, wenn die Seite sonst zu lang würde.

Interaktive Diagramme¶

Du kannst anklickbare Elemente in PlantUML-Zeichnungen erstellen:

Wenn SVGs mit rohem HTML eingebettet werden, denke daran, dass MkDocs den Pfad nicht wie bei normalen Markdown-Bildlinks umschreibt. Verwende den Pfad so, wie er von der generierten Seiten-URL aus erscheint.