zkdoc-action

This GitHub Action builds DocFX docs from the specified TwinCAT PLC. Use with an action such as actions-gh-pages to deploy to your project's GitHub pages site!

Register to use this action for public repositories, this will allow you to run this action 30 times per month. Contact us to retrieve a subscription if you need more builds per month or use Zeugwerk Doc for private repositories either on GitHub or any CI/CD server hosted in the cloud or on-premise or need support.

Demonstration

See this github repository to see how to use zkdoc - https://github.com/stefanbesler/struckig

The resulting documentation can be uploaded either as github pages or to a private webserver which is showcased by the Zeugwerk Development Kit

Syntax

Please see zkdoc to get an overview over special commands that can be used when writing source-code documentation.

Inputs

username: Username of a Zeugwerk Useraccount (Required)
password: Password of a Zeugwerk Useraccount (Required)
filepath: Path to one or more plcproj files, relative to the working directory. Alternatively for applications that are developed with the Zeugwerk Development Kit, which contain a .Zeugwerk/config.json file, the folder of the application can be used. In the latter case, usually filepath=. (Required)
doc-folder: Folder that may contain docfx configuration files such as a docfx.json, see here for a repo, which is using this parameter

Creating secrets

We highly recommend to store the value for username and password in GitHub as secrets. GitHub Secrets are encrypted and allow you to store sensitive information, such as access tokens, in your repository. Do these steps for username and password

On GitHub, navigate to the main page of the repository.
Under your repository name, click on the "Settings" tab.
In the left sidebar, click Secrets.
On the right bar, click on "Add a new secret"
Type a name for your secret in the "Name" input box. (i.e. ACTIONS_ZGWK_USERNAME, ACTIONS_ZGWK_PASSWORD)
Type the value for your secret.
Click Add secret.

Example usage

name: Documentation
on:
  workflow_dispatch:
jobs:
  Build:
    name: Documentation
    runs-on: ubuntu-latest
    steps:
      - name: Build
        uses: Zeugwerk/zkdoc-action@1.0.0
        with:
          username: ${{ secrets.ACTIONS_ZGWK_USERNAME }}
          password: ${{ secrets.ACTIONS_ZGWK_PASSWORD }}
          filepath: 'Untitled1/Untitled1.plcproj'
          doc-folder: 'docs'
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_dir: archive/docs/html

Note that the parameter valu for 'doc-folder' appears again in 'publish_dir'

Please see the documentation of peaceiris/actions-gh-pages for generating the secret ACTIONS_DEPLOY_KEY.

Configuration file

This action can optionally use a configuration file, which has to be placed in the folder .Zeugwerk/config.json. The simplest way to generate a configuration file is by using the Twinpack Package Manager.

A typical configuration file for a solution with 1 PLC looks like this (Twinpack generates this for you automatically)

{
  "fileversion": 1,
  "solution": "TwinCAT Project1.sln",
  "projects": [
    {
      "name": "TwinCAT Project1",
      "plcs": [
        {
          "version": "1.0.0.0",
          "name": "Untitled1",
          "type": "Application",
          "packages": [
            {
              "version": "1.2.19.0",
              "repository": "bot",
              "name": "ZCore",
              "branch": "release/1.2",
              "target": "TC3.1",
              "configuration": "Distribution",
              "distributor-name": "Zeugwerk GmbH"
            }
          ],
          "references": {
            "*": [
              "Tc2_Standard=*",
              "Tc2_System=*",
              "Tc3_Module=*"
            ]
          }
        }
      ]
    }
  ]
}