plcdoc 0.0.1

Description:

plcdoc 0.0.1

PLC Sphinx Parser



This is a work-in-progress of a tool to get documentation with Sphinx from TwinCAT PLC.
The focus is on PLC code made with Structured Text (ST), i.e. the IEC 61131-3 standard.
At the basis is the TextX package to parse some of the PLC code.
This package allows for recognition of ST code such that definitions can be manually typed in.
More useful however is the feature to automatically parse declarations from ST and insert the results in your Sphinx
document.
Why
TwinCAT has a built-in documentation system. However, it is only semi-official and it cannot be exported to stand-alone
documents. Currently it is common to write your program documentation externally and attach it with your source. The
downsides of this approach are clear: structural or name changes must all be done twice, which can be easily forgotten.
It would be ideal to, like with many modern languages, produce from-source documentation on the fly with continuous
integration. This way you can focus exclusively on your code while up-to-date docs are always available.
How to use
Warning: plcdoc is still in development and although some documentation can be made, you will likely run into many warnings and errors.
Install
Install from pypi.org with:
pip install plcdoc

Configuration
In your conf.py, add the extension:
extensions = ["plcdoc"]

For automatic source parsing, either list your PLC source files:
plc_sources = [
"path/to/file1.TcPOU",
# ...
]

And/or list a project file directly:
plc_project = "path/to/project.plcproj"

When using a project file it will be scoured for listed sources and those sources will be included directly.
Manual typing
You define Structured Text objects like so:
.. plc:function:: MyFunction(myFloat, myInt) : BOOL

:param REAL myFloat: First variable
:param UDINT myInt: Second variable, very important

This is the general description.

Auto typing
You can insert in-source definitions like this:
.. plc:autofunction MyFunction

Structured Text doc comments
Follow the Beckhoff comment style
to allow parsing from source. Fortunately, this is close to e.g. the Python style of doc comments.
For example, the declaration to make the plc:autofunction above give the same result as the plc:function could be:
(*
This is the general description.
*)
FUNCTION MyFunction : BOOL
VAR_INPUT
myFloat : REAL; // First variable
myInt : UDINT; // Second variable, very important
VAR_END

Types, arguments, etc. are deduced from the source code itself and corresponding comments are put alongside.
Possibilities and limitations
The goal is that all code inside <Declaration></Declaration> tags can be parsed. Everything outside, e.g. inside
<Definition></Definition> tags, cannot and will be ignored.
Although all common notations should be supported, due to the flexibility of Structured Text (and any programming
languages in general), there will be cases where source parsing fails. It is recommended to set up docs generation
early on to identify failures quickly.
The biggest source of errors inside declarations is initial expressions. For example, a variable could be initialized
as a sum, involving other variables, and include various literal notations. This is hard to capture in full.
Developing
Setup
Get the development tools and make your installation editable by running:
pip install -e .[test,doc]

Tests
Run all tests with python -m pytest.
The structure is based on the Sphinx unittest principle. There are actual doc roots present which are processed as
normal during a test.
Run with coverage with python -m pytest --cov. Add --cov-report=html to produce an HTML test report.
Basis and inspirations
There are a bunch of projects linking new languages to Sphinx:

C++: https://github.com/breathe-doc/breathe (language, typing and auto-doc)
MATLAB: https://github.com/sphinx-contrib/matlabdomain (language, typing and auto-doc)
JavaScript: https://github.com/mozilla/sphinx-js (language, typing and auto-doc)
Python (autodoc): https://github.com/sphinx-doc/sphinx/tree/master/sphinx/ext/autodoc (auto-doc)

breathe is the biggest and most complete, but very abstract. sphinxcontrib-matlabdomain was the main inspiration for
the package layout. The auto-documentation however mimics the default Python autodoc extension very closely.
References
Other useful projects:

TcTools:

A package with helper tools for developing TwinCAT PLC code (also made by us).


Blark:

Parsing of PLC Structured Text code in Python using Lark.
Very impressive and much more complete than the PLC parsing done here, but slight overkill for the purpose here.


TcBlack:

Black-inspired formatting tool for PLC Structured Text.