Merge branch 'main' into feature/wikiRunnerExecuteCommand

Author: EduardKrieger

documentation/Definition of DONE.md

@@ -0,0 +1,45 @@
+# **General**
+* I kept the name of my tutorial short. For a small explanation of my tutorial, I used sub-topics.
+* I described what I wanted to train in a few words and clearly state the objective of my tutorial. This should give the reader an idea of what to expect from my tutorial and help them to determine if they really want to learn this topic.
+* I addressed the user directly.
+* I was clear and concise in my writing. 
+* I provided links for further related topics.
+* I did not just copy and paste the documentation into a tutorial. I broke down the information into smaller and more simple packages.
+* I want to teach something. Therefore, I did not just write down the steps and results but explained why this step was necessary.
+* I rather made many small steps than a few big steps.
+* I used images and code examples in my tutorial which were provided in the devonfw documentation. Plain text gets boring after time.
+* I used an organized structure in my tutorial.
+* All the things that the user should do actively, I have always written with function calls and steps . I have not given any instructions for action in text form.
+* I proofread my tutorial:
+     1. Are the steps available and in the correct order? 
+     1. Are there any spelling mistakes? 
+     1. Does everything make sense?
+* I ran through the latest update of my tutorial in Katacoda-Dev and checked if everything was working as intended BEFORE requesting a review.
+
+# **Technical**
+* The files that were used in `nextKatacodaStep `are available in `.asciidoc` files and do not contain Katacoda Syntax. `nextKatacodaStep` is almost never needed.
+* Commands like `--- cd devonfw {{execute T1}} ---` should not be used, as it could break certain functions.
+
+# Different types of tutorials
+* “Learning”: The user gets a detailed explanation of certain code/feature/functionality.
+* “Quick Start”: Implementing code/feature without comprehensive explanation
+* “Try Out”: The user gets a working sample project (like MyThaiStar), suitable for showcasing functionalities and ease of use.
+
+# **Additional things to consider**
+
+### Only for Learning-tutorials:
+
+* I provided a detailed explanation of the topic in a way, that everybody can understand it.
+* I used more theory and less practice.
+
+### Only for Quick Start-tutorials:
+
+* I implemented a certain functionality straightforward without any comprehensive explanation.
+* I emphasized practice, and used less theory.
+* I only provided the information which is really needed to understand what I did in the tutorial. 
+* For comprehensive explanation of the everything what I have done in the tutorial, I provide links to either the devonfw documentation or the specific Learning-tutorial of the topic (if there is any).
+
+### Only for Try Out-tutorials:
+
+* I wanted to showcase a certain sample project/feature and its capabilities in a fast and straightforward way to the reader. Example: Tutorial for launching MyThaiStar, so the reader can click through it, and see what is possible.
+* I provided little explanation of the things done in the tutorial.

documentation/Functions.md

@@ -3,6 +3,9 @@
 To download and setup the tutorial-compiler use the description in the setup section.<br/>
 [Setup](https://github.com/devonfw-tutorials/tutorial-compiler/wiki/Setup)
 
+If you want to know if your tutorial meets the general requirements, check out the Definition of DONE<br/>
+[Definition of DONE](https://github.com/devonfw-tutorials/tutorial-compiler/wiki/Definition-of-DONE)
+
 The Development section may help you to contribute code to the tutorial-compiler.<br/>
 [Development](https://github.com/devonfw-tutorials/tutorial-compiler/wiki/Development)
 

documentation/Home.md

@@ -11,8 +11,12 @@
     |-- tutorials
         |-- [playbook-name]
             /--index.asciidoc
+            |-- images
+                /--image.jpg
+            
 
-Write your own tutorials in "./tutorials/[playbook-name]/index.asciidoc".
+
+Write your own tutorials in "./tutorials/[playbook-name]/index.asciidoc". Images must be saved in a folder called `images`.
 You will find all the details in the tutorials [Developement](https://github.com/devonfw-tutorials/tutorials/wiki/Development) page.
 
 

documentation/Structure.md

@@ -9,6 +9,7 @@ Every tutorial has three main parts
 * at least one step
 Additionally, there are optional parts
 * a subtitle
+* tags
 * a conclusion of the tutorial. This will be shown at the last page and can be used to summarize the learned, to foreshadow the next steps on the learning path or to mention useful sources.
 
 The tutorials are written in asciidoc files. 
@@ -94,6 +95,22 @@ functionName2(parameters)
 --
 ```
 
+To display images within a step, you can use either the [displayContent](https://github.com/devonfw-tutorials/tutorial-compiler/wiki/Functions#displayContent) function or the following syntax in the index.asciidoc file:
+```
+![alternative text](./assets/image.jpg)
+```
+The image must be in a folder called `images` in the folder of the playbook (see [Structure](https://github.com/devonfw-tutorials/tutorial-compiler/wiki/Structure)).
+
+There is the option to add tags to your tutorials. To do that, you have to add the following syntax after the title or if you have specified a subtitle, after the subtitle.
+
+````
+[tags]
+--
+tagType=tag0;tag1
+tagType=tag0;tag1;tag2
+--
+```
+
 You can also add an optional conclusion text, which is shown on completion of the tutorial. Use this to summarize the important content of the tutorial, to point out what to learn next or to mention other useful informations.
 
 To do that, you have to provide the conclusion at the end of the tutorial (after the last step) surrounded by ```====```.
@@ -110,11 +127,17 @@ These blocks are combined to a complete tutorial.
 ```
 = Title
 == Subtitle
+[tags]
+--
+tagType=tag0;tag1
+tagType=tag0;tag1;tag2
+--
 ====
 Description of the tutorial
 ====
 
 The explanation for the step 1
+![alternative text](./assets/image.jpg)
 [step]
 --
 functionName1(parameters)

documentation/Tutorials.md

@@ -1,10 +1,11 @@
 start
   = headline
     subtitle?
+    tags?
     description
     steps
     conclusion?
-
+    
 headline "headline starting with ="
   = "=" _ string ___
 
@@ -83,6 +84,18 @@ conclusionlines
 conclusionline
   = !blockmarker string __ 
 
+tags
+  = "[tags]" ___
+    "--" ___
+    taglines
+    "--" __
+
+taglines
+  = tagline+ { return { "taglines": text()}; }
+
+tagline
+  = !"--" string __ 
+
 string "string"
   = [^\r\n]+ { return text(); }
 

engine/parser.def

@@ -20,9 +20,10 @@ export class Parser {
         let result = new Playbook();
         result.title = parseResult[0][2];
         result.subtitle = parseResult[1]? parseResult[1][3]: "";
-        result.description = parseResult[2][2].descriptionlines;
-        result.conclusion = parseResult[4]? parseResult[4][2].conclusionlines: "";
-        for(let index in parseResult[3]){
+        result.tags = this.getTags(parseResult);
+        result.description = this.insertNewlineIntoDescription(parseResult[3][2].descriptionlines);
+        result.conclusion = this.insertNewlineIntoDescription(parseResult[5]? parseResult[5][2].conclusionlines: "");
+        for(let index in parseResult[4]){
             let step = new Step();
             step.text = this.getText(parseResult, index);
             step.lines = this.getLines(parseResult, index);
@@ -35,26 +36,26 @@ export class Parser {
 
     getText(parseResult, index){
         try {
-            return parseResult[3][index][1].steptextlines || parseResult[3][index][2][1].steptextlines;
+            return parseResult[4][index][1].steptextlines || parseResult[4][index][2][1].steptextlines;
         } catch (error) {
-            return parseResult[3][index][2][1].steptextlines;
+            return parseResult[4][index][2][1].steptextlines;
         }
     }
 
     getLines(parseResult, index):Command[]{
         let linebreak = process.platform=="win32" ? "\r\n" : "\n";
         try {
-            return (parseResult[3][index][7].steplines || parseResult[3][index][2][7].steplines).split(linebreak).filter(e => e.trim() != '').map(e => this.createCommand(e));
+            return (parseResult[4][index][7].steplines || parseResult[4][index][2][7].steplines).split(linebreak).filter(e => e.trim() != '').map(e => this.createCommand(e));
         } catch (error) {
-            return parseResult[3][index][2][7].steplines.split(linebreak).filter(e => e.trim() != '').map(e => this.createCommand(e));
+            return parseResult[4][index][2][7].steplines.split(linebreak).filter(e => e.trim() != '').map(e => this.createCommand(e));
         }
     }
 
     getTitle(parseResult, index) {
         try {
             // parseResult[3][index][4][2] step without block
             // parseResult[3][index][2][4][2] step inside a block
-            return (parseResult[3][index][4][2].steptitle || parseResult[3][index][2][4][2].steptitle);
+            return (parseResult[4][index][4][2].steptitle || parseResult[4][index][2][4][2].steptitle);
         } catch(error) {
             return null;
         }
@@ -76,9 +77,46 @@ export class Parser {
 
     getTextAfter(parseResult, index){
         try {
-            return parseResult[3][index][3].steptextafterlines || "";
+            return parseResult[4][index][3].steptextafterlines || "";
         } catch (error) {
             return "";
         }
     }
+
+    getTags(parseResult){
+        let tagDict = {};
+        try{
+            let results = parseResult[2] ? parseResult[2][4].taglines.split(/\r?\n/) : Array();
+            for (let result of results){
+                if(result){
+                    result = result.split("=")
+                    let type = result[0];
+                    let tags = result[1].includes(";") ? result[1].split(";") : Array(result[1]);
+                    tagDict[type] = tags;
+                }
+            }
+        }catch (error) {
+            throw error;
+        }        
+        return tagDict;
+    }
+
+    insertNewlineIntoDescription(description: string): string{
+        let result = description;
+        let offset = 0;
+        for(let i = 0; i < description.length-1; i++){
+            if(description[i] == '#' && description[i+1] == '#' && description[i+2] == '#'){
+                let temp = result.slice(0,i+offset);
+                result = temp +"\n"+result.slice(i+offset);
+                offset++;
+            }
+            if(description[i] == '*'){
+                let temp = result.slice(0,i+offset);
+                result = temp +"\n"+result.slice(i+offset);
+                offset++;
+            }
+
+        }
+        return result;
+    }
 }

engine/parser.ts

@@ -8,4 +8,5 @@ export class Playbook{
     public description: string;
     public conclusion: string;
     public steps: Step[] = [];
+    public tags: Record<string, string[]>;
 }

engine/playbook.ts

@@ -1,23 +1,30 @@
 import { Runner } from "./runner";
 import { Playbook } from "./playbook";
+import { RunCommand } from "./run_command";
 import * as fs from "fs";
 import * as path from "path";
 import * as ejs from "ejs";
 
 export abstract class WikiRunner extends Runner {
 
     public outputPathTutorial: string;
+    public commandCntMap = new Map();
+
+    protected readonly INSTALLED_TOOLS: string = "installedTools";
     protected fileTypeMap = new Map([ [".java", "java"],[".ts", "typescript"],
     [".js", "javascript"], [".html", "html"],
     [".scss", "css"], [".asciidoc", "asciidoc"], ]);
-    protected readonly INSTALLED_TOOLS: string = "installedTools";
+    
 
 
     init(playbook: Playbook): void {
         let outputDirectory = this.createFolder(path.join(this.getOutputDirectory(), "wiki", this.environmentName), false)
         this.outputPathTutorial = this.createFolder(path.join(outputDirectory, playbook.name), true);
         this.setVariable(this.WORKSPACE_DIRECTORY, path.join(this.getWorkingDirectory()));
         this.setVariable(this.INSTALLED_TOOLS, "");
+        for(let i = 0; i< playbook.steps.length; i++){
+            this.commandCntMap.set(i, playbook.steps[i].lines.length-1);
+        }
     }
 
     async destroy(playbook: Playbook): Promise<void> {
@@ -31,4 +38,22 @@ export abstract class WikiRunner extends Runner {
         fs.writeFileSync(tempFile, result, { flag: "a" });
     }
 
+    protected checkForText(runCommand: RunCommand): string{    
+        return runCommand.lineIndex == 0 
+            ? runCommand.text
+            : undefined; 
+    }
+
+    protected checkForTitle(runCommand: RunCommand): string{    
+        return runCommand.lineIndex == 0 
+            ? runCommand.stepTitle
+            : undefined; 
+    }
+
+    protected checkForTextAfter(runCommand: RunCommand): string{
+        return this.commandCntMap.get(runCommand.stepIndex) == runCommand.lineIndex 
+            ? runCommand.textAfter
+            : undefined;
+    }
+
 }

engine/wikiRunner.ts

@@ -413,7 +413,7 @@ export class Console extends Runner {
         return result;
     }
 
-    runNextKatacodaStep(runCommand: RunCommand): RunResult {
+    runDisplayContent(runCommand: RunCommand): RunResult {
         //Only needed for katacoda and wiki runner
         return null;
     }
@@ -591,8 +591,8 @@ export class Console extends Runner {
             .noErrorCode(result)
             .noException(result)
             .directoryExits(path.join(this.getWorkingDirectory(), "devonfw", "software", "cobigen-cli"))
-            .fileExits(path.join(this.getWorkingDirectory(), "devonfw", "software", "cobigen-cli", "cobigen.jar"))
-            .fileExits(path.join(this.getWorkingDirectory(), "devonfw", "software", "cobigen-cli", "cobigen"));
+            .fileExits(path.join(this.getWorkingDirectory(), "devonfw", "software", "cobigen-cli", "lib", "cli.jar"))
+            .fileExits(path.join(this.getWorkingDirectory(), "devonfw", "software", "cobigen-cli", "bin", "cobigen"));
         } catch(error) {
             await this.cleanUp();
             throw error;
@@ -941,16 +941,6 @@ export class Console extends Runner {
             for(let asyncProcess of this.asyncProcesses) {
                 killProcessesRecursively(systemProcesses, asyncProcess.pid);
             }
-        }
-        for(let proc of systemProcesses){
-            if(path.normalize(proc.path).includes(path.normalize(this.getWorkingDirectory()))){
-                try {
-                    process.kill(proc.pid);
-                } catch(e) {
-                        console.error("Error killing process "+proc.name+" with id: " + proc.pid , e);
-                }
-            }
-        }
             //Check if there are still running processes on the given ports
             // Maybe not needed anymore can be deleted and the function documentation should be updated
             for(let asyncProcess of this.asyncProcesses.reverse()) {
@@ -964,10 +954,19 @@ export class Console extends Runner {
                             }
                         }
                     }
-                }      
-            
-
+                }
+        }
+        systemProcesses = await snapshot("name", "pid", "ppid", "path");      
+        for(let proc of systemProcesses){
+            if(path.normalize(proc.path).includes(path.normalize(this.getWorkingDirectory()))){
+                try {
+                    process.kill(proc.pid);
+                } catch(e) {
+                    console.error("Error killing process "+proc.name+" with id: " + proc.pid , e);
+                }
+            }
         }
+    }
 
     private async cleanUp(): Promise<void> {
         await this.killAsyncProcesses();