Let’s try to generate documentation based on our own templates. This tutorial will focus on documentation for equipment characterization typically done by the colleagues of Deployment Services.
Topics
- Overview and Motivation
- Dependencies & Installing
- Generating Documentation
- Creating your Templates
Overview and Motivation
One of the more difficult tasks a software developer has is producing documentation. Documentation is a very hard process, because it requires someone that understands profoundly the topics he is writing about, but at the same time is able to write in a way that is free from the assumptions and biases he has. Templating is good way to guide the writer into have a standardized approach to writing documentation and helping him with a set structure of topics he has to gather and fill.
The goal of this tool is to make it easier to write documentation and standardize the documentation through different use cases and in different teams. Also, the goal is to have it in such a way, where even people that are not developers are able to use and contribute.
Dependencies & Installing
This tool requires the pre installation of:
The tool is based on a visual studio code extension called VSCode Folder Templates, also for convenience it installs an extension for mermaid VSCode Markdown Mermaid. Mermaid is a tool to generate diagrams and more information on how to generate diagrams can be found here Mermaid and they also provide a very helpful Mermaid Live Editor.
To install the tool:
npm install @criticalmanufacturing/doc-gen --registry=https://dev.criticalmanufacturing.io/repository/npm-public --global
The tool provides a set of predefined templates that you can import in your vscode, these templates can also receive inputs.
Generating Documentation
Right now, the tool only has templates for IoT documentation. So the command available is to install IoT templates.
In order to install the IoT templates, you can run:
cmf doc-gen install iot
The command supports generating to a particular folder using pathForTemplates. The command also allows to add an exception in your .gitignore file, to not commit your templates with --persistInProject, if false it will add to the exclusions. It also has another option which is --localInstall, if this is passed as false it will install globally and be available every time you open vscode.
By default it adds the exclusion in your .gitignore file if it exists and creates locally.
The templates will be generated in a folder called .fttemplates:
In order to use them, just right-click and select Create New Templated Folder, select the template and fill the inputs:
Ok, we have created our template and now we can edit it!!!
Creating your Templates
If you want to add your own templates, you can edit what is under .fttemplates, and edit existing or add new one’s. If, for example in your project you want to add templates, make sure to commit the folder .fttemplates, so you don’t lose them.
All the documentation on how to create templates is in VSCode Folder Templates and also, you can check all our examples. Feel free to suggest new templates and to contribute. The source code for this plugin is currently under Devops doc-gen
Author
Hello 👏 , my name is João Roque ✌️
I’ve been working for some years at Critical Manufacturing. I split my time working in the IoT Team and working with the project’s teams. You can visit me at https://j-roque.com/ or check me at LinkedIn
Skills: Connect IoT / DevOps
