Documentation
Zeugwerk Documentation is a tool for automatic documentation generation for TwinCAT PLC projects. It is available as a CLI (zkdoc) for integration in a CI/CD environment and as an integration into the TcXAEShell as part of the Zeugwerk Creator.
Automatic documentation generation is essential for several reasons, particularly in the context of software development:
- Time Efficiency: Comprehensive documentation can be generated in a fraction of the time it would take to write manually, allowing developers to focus more on coding and problem-solving
- Consistency Across Projects: It helps maintain a uniform documentation style across multiple projects, enhancing readability and reducing the time needed for new team members to onboard
- Real-time Accuracy: As the codebase evolves, so does the documentation. Updates can be made in real-time, ensuring that the documentation always reflects the current state of the project
- Enhanced Collaboration: Clear and up-to-date documentation facilitates better teamwork, smoother code reviews, and more efficient debugging processes
- Reduced Technical Debt: Keeping documentation current is an investment in the long-term health of your projects, reducing future maintenance headaches.
In essence, automatic documentation generation is not just about improving documentation, it is about elevating the entire development workflow. It streamlines processes, improves code quality, and fosters a culture of clear communication within engineering teams.
Syntax
Please see zkdoc to get an overview over writing source-code documentation.
TcXAEShell Integration
To genearate documenation from a TwinCAT PLC project directly from TcXAEShell, you need the Zeugwerk Creator as an extension for the TwinCAT IDE. To get a full functional trial license, download and install the Zeugwerk Development Kit.
In the PLC node context menu you can conveniently start the documentation generation for the opened PLC project.
In the output window you can see the progress and link to the generated documentation.
Customizing documentation
On the homepage of the generated documentation you get information about the folder structure how to use Markdown and toc files to create add your own custom documenation.
Note that the folder reference is autogenerated by zkdoc and contains all source code documentation for your project. Use the options described to create your own additional documenation for topics like maintenance information, operator instructions, ...
Options
Zeugwerk Documenation can be parameterized through the options dialog in Visual Studio (TcXAEShell).
