Skip to content

Development

Jump to bottom
GuentherJulian edited this page Mar 23, 2021 · 17 revisions

Development

In this section we will describe how you can implement your own tutorials.

How to create a playbook

Every tutorial has three parts

  • title
  • a description of the tutorial. Here you should tell the user what he is going to learn in this tutorial.
  • at least one step

The tutorials are written in asciidoc files. To create a tutorial you have to create a new folder for your tutorial. In this new folder you have to create a file called index.asciidoc

The three parts of the tutorial will be written in this file. Put the title of the tutorial in the first line:

= Title

In the next lines, you have to provide the description of the tutorial surrounded by ====.

====
Description of the tutorial
====

The description is followed by the steps. Every step has

  • an explanation
  • a function to execute (see the function list in this wiki)
  • and an optional explanation of the results of the step.

The easiest is a step without the optional explanation of the results of the step. This step is created by the following syntax block

The explanation for the step
[step]
--
functionName(parameters)
--

If you want to explain the results to the user use the following syntax block with the surrounding ====:

====
The explanation for the step
[step]
--
functionName(parameters)
--
The explanation of the results
====

These blocks are combined to a complete tutorial.

= Title
====
Description of the tutorial
====

The explanation for the step 1
[step]
--
functionName1(parameters)
--

The explanation for the step 2
[step]
--
functionName2(parameters)
--

====
The explanation for the step 3
[step]
--
functionName3(parameters)
--
The explanation of the results
====

The explanation for the step 4
[step]
--
functionName4(parameters)
--

Generate the tutorial

The easiest way to generate the tutorial is to create a pull request with your playbook in the tutorials repository. To do this, you need to fork this repository. The playbook in your pull request will be build automatically and published to https://katacoda.com/devonfw-dev.
A tutorial which explains this process is available on the devonfw katacoda account (https://katacoda.com/devonfw/scenarios/tutorial-compiler).

In advanced cases and for troubleshooting you can run the build on your local maschine. The generation of the tutorial is done by the tutorial-compiler (https://github.com/devonfw-tutorials/tutorial-compiler). You can find a description how to set up the compiler on your local machine in the tutorial-compiler repository.
https://github.com/devonfw-tutorials/tutorial-compiler/wiki/Setup

Clone this wiki locally