Documentation with MkDocs¶

This project uses MkDocs with the Material theme for structured engineering documentation. Write pages in Markdown, keep source files under docs/, and update mkdocs.yml when a page should appear in the navigation.

Local Commands¶

Run from the repository root:

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

Use pcs docs serve while editing and pcs docs open to open the local site in the default browser. Use pcs docs render after changing PlantUML diagrams. Use pcs docs build before publishing or committing larger documentation changes. pcs init creates the virtual environment and installs the pinned documentation packages.

Headings and Text¶

Use headings to create a clear page structure. MkDocs builds the page table of contents from headings.

# Page Title

## Main Section

### Detail Section

Prefer short paragraphs and direct wording. Use inline code for PLC symbols, file names, commands, and configuration keys such as pcs.config.json, FB_CellDemo, or xuiSignalRange.

Lists¶

Use unordered lists for related items:

PLC source files live in tia/exports.
PLC source files are grouped by subsystem, with .scl, .db, and .udt files living together.
Deployment targets are configured in pcs.config.json.

Use numbered lists for procedures:

Edit the source file.
Deploy to TIA Portal.
Compile the PLC software.
Review compiler messages.

Tables¶

Tables are useful for parameters, signal maps, and status descriptions.

Signal	Type	Description
`xinRawValue`	`Int`	Raw analog input value from the module
`xuiSignalRange`	`USInt`	Raw range family: unipolar, live-zero, or bipolar
`yrePhysValue`	`Real`	Scaled engineering value
`yboFault`	`Bool`	Summary fault indication

Admonitions¶

Use admonitions for information that must stand out.

Warning

Shutdown sequence must complete before restart.

Note

Use notes for helpful context that is not part of the main procedure.

Tip

Keep reusable command examples in fenced code blocks so they can be copied safely.

Danger

Use danger only for actions that can damage equipment, create unsafe states, or destroy data.

Collapsible Details¶

Use collapsible sections when details are useful but not needed on every read.

Details

Erweiterte Informationen

This is a good place for background, alternative commands, or implementation notes.

Expanded by default

Add a + after the question marks when the section should be open by default.

Tabs¶

Tabs are useful when the same topic has PLC, HMI, simulation, and commissioning views.

PLCHMICommissioning

PLC Beschreibung

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

HMI Beschreibung

Show operator-facing labels, alarms, and status fields here.

Use this tab for checks, expected values, and troubleshooting hints.

Code Blocks¶

Use fenced code blocks with a language name.

.\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¶

Use relative links for pages inside the documentation:

Use normal Markdown links for external references:

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

Images and Diagrams¶

Store PlantUML source and rendered SVG files next to each other when possible.

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

Reference rendered SVGs from Markdown:

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

MkDocs does not render .puml files automatically in the current setup. Render diagrams from the repository root before building the docs:

pcs docs render
pcs docs build

pcs docs build asks whether diagrams should be rendered first. For documentation changes that include PlantUML edits, answer Y or run pcs docs render explicitly before the build.

Math¶

Inline math can be written as \( y = mx + b \).

Block math:

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

Rendered:

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

Useful Patterns¶

Use parameter tables for PLC blocks:

Parameter	Direction	Type	Meaning
`xinRawValue`	Input	`Int`	Raw channel value
`xrePhysMin`	Input	`Real`	Physical value at minimum signal
`xrePhysMax`	Input	`Real`	Physical value at maximum signal
`yboValid`	Output	`Bool`	Scaled value can be used

Use status tables for diagnostics:

Status	Meaning	Operator Action
`yboWireBreak`	Live-zero signal below valid range or hardware diagnostic active	Check wiring and transmitter
`yboOverflow`	Raw value above module representation	Check channel configuration and signal
`yboUnderflow`	Raw value below module representation	Check channel configuration and signal
`yboRangeError`	Raw value outside nominal configured range	Check sensor and process condition

Use tabs when one topic has multiple audiences, and collapsible details when the page would otherwise become too long.

Interactive diagrams¶

You can create clickable elements in the PlantUML drawings:

When embedding SVGs with raw HTML, remember that MkDocs does not rewrite the path like it does for normal Markdown image links. Use the path as it will appear from the generated page URL.