zkdoc (on-premises)

One of Zeugwerk’s CI/CD tools for TwinCAT. The zkdoc command-line tool generates API documentation from your TwinCAT projects and builds HTML sites with DocFX. This is the on-premises / licensed option: run zkdoc in your own CI/CD or on your machine. For generating docs in GitHub with no local setup, use zkdoc-action. Comment syntax: Syntax reference.

zkdoc extracts documentation from PLC source, analyzes structure (dependencies, cross-references), and produces Markdown. With the DocFX option it also prepares a DocFX project so you can build and serve HTML.

Availability

Open source — Use zkdoc-action (GitHub Action); no CLI license needed.
Private repos / on-premises — zkdoc as an online service for private repositories: contact us.
On-premises CLI — Licensed command-line tool for any pipeline that can run Windows .NET executables. Trial available; contact us.

This page describes the CLI usage.

Installation & licensing

Zeugwerk provides zkdoc as a ZIP archive. Extract it to a folder on your machine (e.g. C:\zkdoc\...). Open a command prompt in that folder and run zkdoc.exe. Without a license you’ll see a message indicating that a license is required.

Place the license.lic file (from Zeugwerk) in the same folder as the executable and run zkdoc again to confirm it runs. A trial license is available on request.

DocFX — To produce HTML, you need DocFX. Download and extract it and add docfx.exe to your PATH (or run it by full path). zkdoc only generates the input for DocFX; you run DocFX yourself.

Usage

We use the DeviceInfo library as an example. For all options run:

zkdoc.exe --help

Generate Markdown and DocFX files

zkdoc can extract documentation (including inheritance, relationships, method signatures) and write Markdown into a reference subfolder in your output directory. To get a DocFX-ready site, add -x (and always use -m for Markdown):

zkdoc.exe -x -m -o "C:\libdoc\multi" "C:\libs\DeviceInfo\src\DeviceInfo\DeviceInfo\DeviceInfo.plcproj"

If you omit -o, output goes to a documentation/reference subfolder next to the zkdoc executable.

Multiple projects — List several .plcproj paths; zkdoc combines them into one documentation set:

zkdoc.exe -x -m -o "C:\libdoc\multi" "C:\path\to\ProjectA.plcproj" "C:\path\to\ProjectB.plcproj"

Build HTML with DocFX

After zkdoc has run, build the site with DocFX (the path is the one where zkdoc wrote docfx.json):

docfx.exe build "C:\libdoc\deviceinfodoc\docfx.json"

Output is in the html subfolder. To preview locally:

docfx.exe --serve "C:\libdoc\deviceinfodoc\docfx.json"

Note

If docfx.json already exists in the output folder, zkdoc does not overwrite it, so you can keep your own template or styling. See DocFX templates.

Useful options

Option	Description
`-o`, `--output`	Output directory. Created if missing. Use quotes if the path has spaces.
`-f`, `--filter`	Exclude paths by regex. Default exclusions: `_Test`, `_Tests`, `Examples`. Example: exclude `_Internal` and `_Internals`: `--filter "((_)Internal[s]\\.*?)"`
`--include-internal`	Include objects marked INTERNAL in source (otherwise excluded).
`--exclude-private`	Exclude private methods from the API docs.
`--exclude-protected`	Exclude protected methods from the API docs.
`--depth`	Maximum category depth in the doc (default 1). Increase to show deeper hierarchy.

Summary

Install zkdoc and (for HTML) DocFX; add the license file.
Run zkdoc -x -m -o <out> <path-to.plcproj> (and optionally more projects).
Run docfx build <out>/docfx.json and open or serve the generated html folder.

For comment syntax, cross-references, and DocFX features, see Syntax reference.

Table of Contents