Development

Development

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

How to create a playbook

To create a tutorial you have to use the following asciidoc syntax in playbooks/*/index.asciidoc:

= Headline
====
Description
====

Instructions for the step 1
[step]
--
functionName1(parameters)
--

Instructions for the step 2
[step]
--
functionName2(parameters)
--

To generate the tutorial you have to start the build script (buildRun.ps1 or buildRun.sh).

How to create your own command

To create a new command you can use in your playbooks, you have to implement a new function for this command in all runner class you want to support this command. If you want to use the command only in katacoda tutorials for example, you have to implement the function only in the katacoda runner class.

The new method must match the following syntax: 'run' + name of the command. The first letter after 'run' has to be in upper case letters.

runYourCommand(step: Step, command: Command): RunResult {
    ...your code...
    let result = new RunResult();
    result.returnCode = 1;
    return result;
}

With the RunResult object you can return a value after the function has executed. You can check this result in the assertions for example and verify if the method has executed properly.

How to create an assertion

Assertions are implemented in the 'assertions' folder of the tutorial-compiler directory. To implement a new assertion create a new typescript file with the name of your assertion in this directory.

Inside the new typescript file create a new class. The class has to to implement a static 'run' method as shown below. In this method you can check whatever you want.

export class YourAssertionCode {
    public static run(): void {
        ...your code goes here...
        if(somethingIsWrong){
            throw new Error("Your error message");
        }
    }
}

After this you have to add the newly created assertion to the Assertion class of the index.ts file. This file is located in the same directory.

public yourAssertionCode(): Assertions {
        YourAssertion.run();
        return this;
    }

If you want to pass arguments to this method, you have to do this in the header of the 'run' method and in the call of the method.