Merge pull request #72 from GuentherJulian/tutorial/tutorial-compiler

tutorial-compiler tutorial

Author: GuentherJulian

create-your-own-tutorial/files/alternativeSyntax.md

@@ -0,0 +1,14 @@
+If you want to add some additional text after the step to explain the results of a step then you have to use the following syntax.
+
+```
+====
+The explanation for the step
+[step]
+--
+functionName(parameters)
+--
+The explanation of the results
+====
+```
+
+Here the whole block has to be surrounded by `====`.

create-your-own-tutorial/files/createNewBranch.md

@@ -0,0 +1,11 @@
+Create a new branch inside the cloned repository.
+
+Navigate into the tutorials directory.
+
+`cd tutorials`{{execute T1}}
+
+Create a new branch for your tutorial and switch into this branch.
+
+`git branch tutorial/myOwnTutorial`{{execute T1}}
+
+`git checkout tutorial/myOwnTutorial`{{execute T1}}

create-your-own-tutorial/files/createPullRequest1.md

@@ -0,0 +1,14 @@
+Before starting write content into the tutorial, you have to create a pull request from your newly created branch into the main repository.
+This has the advantage that your tutorial will automatically be build and pushed to https://katacoda.com/devonfw-dev. So you can directly test it.
+
+For this step you need to open you local terminal at your forked and cloned 'tutorials' folder and run the following commands:
+1. 'git add .' 
+2. 'git commit -m "initial commit for tutorial myTutorial"'
+3. 'git push'
+
+This will save all the changes and push them into your tutorials GitHub repository. 
+
+Switch to your browser and open:
+https://github.com/devonfw-tutorials/tutorials
+
+Click on 'Pull requests' > 'New pull request'.

create-your-own-tutorial/files/createPullRequest2.md

@@ -0,0 +1,15 @@
+
+Select
+
+    * base repository: devonfw-tutorials
+    * base: main
+    * head repository: [your username]/tutorials
+    * compare: [your branch name]
+
+and finally create the pull request by clicking on 'Create pull request'.
+
+Write 'WIP:' in front of the pull request title to show that you are still working on this pull request. 'WIP' stands for 'Work In Progress'.
+
+A workflow in the tutorials repository will build the tutorial. Currently the pipeline will fails because a tutorial must contain at least a title, a description and one step.
+
+Let's fix that and fill the tutorial.

create-your-own-tutorial/files/description.txt

@@ -0,0 +1,6 @@
+= Title of my new tutorial
+====
+In this section you can write the description of the tutorial. This can consist of several lines.
+
+The description should explain the tutorial in a few words and explain what is to be learned.
+====

create-your-own-tutorial/files/localTesting.md

@@ -0,0 +1,34 @@
+Now you should have a ideo how to create your own tutorials.
+
+There is also a way to test your tutorials on your local machine. For this you have to clone the tutorial-compiler repository.
+
+The directory with the tutorial-compiler has to be located next to the directory with the tutorials repository.
+
+So go back to the root directory and clone the repository.
+
+`cd /root`{{execute T1}}
+
+`git clone https://github.com/devonfw-tutorials/tutorial-compiler.git`{{execute T1}}
+
+The tutorial-compiler needs typescript to be installed to work. So install typescript on your machine.
+
+`npm install typescript -g`{{execute T1}}
+
+Now navigate into the tutorial-compiler directory and install the needed dependencies.
+
+`cd tutorial-compiler`{{execute T1}}
+
+`npm install`{{execute T1}}
+
+
+# Test your tutorial locally
+To run the tutorial-compiler execute the following command:
+
+`bash localBuildRun.sh -e katacoda -p myTutorial`{{execute T1}}
+
+This will execute your newly create tutorial in the 'katacoda' environment. If you obmit the '-e' and '-p' paramter, all tutorials are executed in all environments.
+
+The tutorial-compiler now generates the files needed for a katacoda tutorial. You can find the files in the 'build/output/katacoda/myTutorial' directory of the tutorial compiler.
+The step you added to your tutorial is shown in the following file:
+
+`tutorial-compiler/build/output/katacoda/myTutorial/step1.md`{{open}}

create-your-own-tutorial/files/pushTutorial.md

@@ -0,0 +1,13 @@
+You now have a working tutorial.
+
+Push the changes again to GitHub by executing the following commands:
+
+1. 'git add .' 
+2. 'git commit -m "added createFile step to the tutorial"'
+3. 'git push'
+
+This will automatically start the workflow in the tutorials repository.
+
+After a while you can find your tutorial on https://katacoda.com/devonfw-dev.
+
+After you have completed your tutorial and tested it on the katacoda account, remove the 'WIP' from your pull request to show that the tutorial is finished.

create-your-own-tutorial/files/step.txt

@@ -0,0 +1,13 @@
+= Title of my new tutorial
+====
+In this section you can write the description of the tutorial. This can consist of several lines.
+
+The description should explain the tutorial in a few words and explain what is to be learned.
+====
+
+Before the '[step]' keyword the explanation is written.
+The explanation can consist of multiple lines.
+[step]
+--
+createFile("pathToTheFile/fileName.txt")
+--