Skip to content

Commit 40ec0f0

Browse files
dixyushidixyushi
authored
Restructured explanation
1 parent d521e9f commit 40ec0f0

1 file changed

Lines changed: 136 additions & 131 deletions

File tree

‎documentation/Functions.md‎

Lines changed: 136 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -23,17 +23,15 @@ The following functions are already implemented:
2323
* [Docker Functions](#dockerSpecific)
2424
1. [dockerCompose](#dockerCompose)
2525

26-
* [File Functions](#fileSpecific)
26+
* [File And Directory Functions](#fileSpecific)
2727
1. [changeFile](#changeFile)
28-
2. [createFile](#createFile)
29-
3. [displayContent](#displayContent)
30-
4. [downloadFile](#downloadFile)
31-
5. [openFile](#openFile)
28+
2. [createFile](#createFile)
29+
3. [downloadFile](#downloadFile)
30+
4. [openFile](#openFile)
3231

3332
* [Katacoda Environment Functions](#katacodaSpecific)
34-
1. [addSetupScript](#addSetupScript)
35-
2. [executeCommand](#executeCommand)
36-
33+
1. [displayContent](#displayContent)
34+
3735
* [Git Functions](#gitSpecific)
3836
1. [cloneRepository](#cloneRepository)
3937

@@ -42,6 +40,10 @@ The following functions are already implemented:
4240
2. [createFolder](#createFolder)
4341
3. [restoreWorkspace](#restoreWorkspace)
4442

43+
* [Other Function](#otherFunctions)
44+
1. [addSetupScript](#addSetupScript)
45+
2. [executeCommand](#executeCommand)
46+
4547
***
4648

4749
## cobiGenFunctions <a name="cobiGen"></a>
@@ -371,7 +373,7 @@ This function has consist of two parameters.
371373

372374
***
373375

374-
## File Functions <a name="fileSpecific"></a>
376+
## File And Directory Functions <a name="fileSpecific"></a>
375377

376378
### i. changeFile <a name="changeFile"></a>
377379
This function is used to insert, append and replace some text in a file.
@@ -448,61 +450,7 @@ This function will work without a devonfw-ide installation.
448450

449451
***
450452

451-
### iii. displayContent <a name="displayContent"></a>
452-
This function is only used when you want to display content such as text, image or any file content in your tutorial.
453-
454-
#### Parameter:
455-
This function consists of two parameters.
456-
457-
1. First parameter:
458-
- **Required**
459-
- **Type**- String
460-
- **Description**- The title of the step.
461-
462-
Note: The title should never be empty and it is of type string.
463-
464-
2. Second parameter:
465-
- **Required**
466-
- **Type**- Array of JSON objects with files, content, or images to be rendered within the Katacoda step.
467-
- **Description**-This function consists of three attributes. The use for this function is to display an image and some descriptive text. No Katacoda syntax is allowed in the files or the content!
468-
* First attribute: "file": Path to a file whose content is to be displayed in the Katacoda step (e.g. .asciidoc or .txt file). The file should be following the formating of asciidoc files.
469-
* Second attribute: "content": Plain text to be displayed in the Katacoda step. This Text should be following the formating of asciidoc files.
470-
* Third attribute: "image": Path to an image to be displayed in the Katacoda step. It should be placed under subfolder of the playbook directory.
471-
472-
#### Example:
473-
* displayContent("Step title", [{ "file": "files/description.asciidoc" }, { "content": "This is just plain content." }, { "image": "files/image.png" }])
474-
475-
#### Formatting rules for content and .asciidoc or .txt files.
476-
* You can add headers to structure your text. The generated headers are shown in the examples below. The headers should fit into the overall structure of the generated wiki so level 1 header are not allowed, but the other header can be used at your judgement.
477-
* A list always needs an empty newline between the last row and the list.
478-
* Use asciidoc style of links
479-
480-
#### Example for content and .asciidoc or .txt files:
481-
```
482-
Existing header structure
483-
= Level 1: tutorial title
484-
== Level 2: subtitle
485-
=== Level 3: prerequisites and learning goals
486-
== Level 2: steptitle
487-
=== Level 3: titles from functions
488-
==== Level 4: subtitles from functions
489-
== Level 2: conclusion
490-
491-
List:
492-
This an unordered List (The empty line is necessary)
493-
494-
* First Item
495-
* Second Item
496-
497-
Link:
498-
The tutorials repository can be found https://github.com/devonfw-tutorials/tutorials/issues[here].
499-
```
500-
##### Note:
501-
1. You should avoid using any command inside any text file for which you want to display content. This will cause problems with the console runner and the tests.
502-
503-
***
504-
505-
### iv. downloadFile <a name="downloadFile"></a>
453+
### iii. downloadFile <a name="downloadFile"></a>
506454
This function is used to download a file from an external URL.
507455
#### Parameter:
508456
This function consist of 3 parameters.
@@ -526,7 +474,7 @@ The command for execution will be generated by Katacoda runner, so user will hav
526474

527475
***
528476

529-
### v. openFile <a name="openFile"></a>
477+
### iv. openFile <a name="openFile"></a>
530478
This function is used to open a particular file.
531479

532480
#### Parameter:
@@ -542,86 +490,57 @@ This function consist of one parameter
542490

543491
## Katacoda Environment Functions <a name="katacodaSpecific"></a>
544492

545-
### i. addSetupScript <a name="addSetupScript"></a>
546-
This function is used to add a script which is executed on startup of the tutorial.
493+
### i. displayContent <a name="displayContent"></a>
494+
This function is only used when you want to display content such as text, image or any file content in your tutorial.
495+
547496
#### Parameter:
548-
This function consist of two parameters
497+
This function consists of two parameters.
498+
549499
1. First parameter:
550500
- **Required**
551501
- **Type**- String
552-
- **Description**- Path of the script (Linux). Relative to the playbook directory.
553-
2. Second parameter:
554-
- **Required**
555-
- **Type**- String
556-
- **Description**- Path of the script (Windows). Relative to the playbook directory.
557-
558-
#### Example:
559-
* addSetupScript("assets/createProjectScript.sh", "assets/createProjectScript.ps1")
560-
561-
##### Note:
562-
1. For Katacoda, only first parameter is required.
563-
2. The script will run in the background while starting the tutorial. Katacoda user will have to wait till the script execution is in process. Once it is done it, Katacoda user will get the message and then command prompt will be available to Katacoda user.
564-
565-
***
566-
567-
### ii. executeCommand <a name="executeCommand"></a>
568-
This function is used when you want to use a bash (or powershell/cmd on windows) command.
502+
- **Description**- The title of the step.
569503

570-
#### Parameter:
571-
This function consists of four parameters.
504+
Note: The title should never be empty and it is of type string.
572505

573-
1. First parameter:
574-
- **Required**
575-
- **Type**- String
576-
- **Description**-It contains the input which is a command. The command that will be executed on Windows.
577-
578506
2. Second parameter:
579507
- **Required**
580-
- **Type**- String
581-
- **Description**-It contains the input which is a command. The command that will be executed on Linux.
582-
583-
3. Third parameter:
584-
- **Required**
585-
- **Type**- JSON object
586-
- **Description**- This parameter consist of three attribute. It is a JSON object with optional fields
587-
* First attribute: (Optional) Directory where the command will be executed, if not in current directory (relative to workspace)
588-
Example: {"dir": string}
589-
* Second attribute: (Optional) Synchronous or asynchronous process. Use asynchronous when starting a server. Default is synchronous.
590-
Example: {"asynchronous": boolean}
591-
* Third attribute: (Optional) Array of arguments
592-
Example: {"args": string[]}
593-
594-
4. Fourth parameter:
595-
- **Required**
596-
- **Type**- JSON object
597-
- **Description**- This parameter consist of three attributes which are the assertion information. Assertion information is needed if you start a server to check server availability. Only required when you start a asynchronous server. This parameter is only needed when the command is an asynchronous command.
598-
* First attribute: "startupTime" which is the time in seconds to wait before checking if the server is running
599-
* Second attribute: "port" which is the port number on which the server is running
600-
* Third attribute: "path" which is the path to the URL path on which is checked if the server is running
508+
- **Type**- Array of JSON objects with files, content, or images to be rendered within the Katacoda step.
509+
- **Description**-This function consists of three attributes. The use for this function is to display an image and some descriptive text. No Katacoda syntax is allowed in the files or the content!
510+
* First attribute: "file": Path to a file whose content is to be displayed in the Katacoda step (e.g. .asciidoc or .txt file). The file should be following the formating of asciidoc files.
511+
* Second attribute: "content": Plain text to be displayed in the Katacoda step. This Text should be following the formating of asciidoc files.
512+
* Third attribute: "image": Path to an image to be displayed in the Katacoda step. It should be placed under subfolder of the playbook directory.
601513

602-
#### Commands:
603-
It is needed to pass a command for Windows and also for Linux-based systems because both systems will always be tested.
514+
#### Example:
515+
* displayContent("Step title", [{ "file": "files/description.asciidoc" }, { "content": "This is just plain content." }, { "image": "files/image.png" }])
604516

605-
##### Assertion information
606-
startupTime = Time in seconds to wait before checking if the server is running
607-
port: Port on which the server is running
608-
path: The URL path on which is checked if the server is running
609-
interval: The availability of the server is checked in the given interval
610-
* (Required) port: will throw error if no port is given.
611-
* (Optional) path: subpath which should be pinged, i.e: if localhost:8081/jumpthequeue should be checked path should be "jumpthequeue". DEFAULT: ""
612-
* (Optional) interval: interval in seconds in which the server should be pinged until it is available or timeouted. DEFAULT: 5 seconds
613-
* (Optional) startupTime: seconds until a timeout will occur and an error will be thrown. DEFAULT: 10 minutes
517+
#### Formatting rules for content and .asciidoc or .txt files.
518+
* You can add headers to structure your text. The generated headers are shown in the examples below. The headers should fit into the overall structure of the generated wiki so level 1 header are not allowed, but the other header can be used at your judgement.
519+
* A list always needs an empty newline between the last row and the list.
520+
* Use asciidoc style of links
614521

615-
#### Example:
522+
#### Example for content and .asciidoc or .txt files:
523+
```
524+
Existing header structure
525+
= Level 1: tutorial title
526+
== Level 2: subtitle
527+
=== Level 3: prerequisites and learning goals
528+
== Level 2: steptitle
529+
=== Level 3: titles from functions
530+
==== Level 4: subtitles from functions
531+
== Level 2: conclusion
616532
617-
* executeCommand("node", "node" ,{"args": ["-v"]})
618-
Will create a command for executing node -v .
533+
List:
534+
This an unordered List (The empty line is necessary)
619535
620-
* executeCommand("somePollingScript.ps1","bash somePollingScript.sh", {"dir": "data/setup", "args": ["--params 5"]})
621-
Will create a command to execute the script in the directory with the parameter --params 5 and in the current command prompt. The command prompt will be blocked until you stop the script.
536+
* First Item
537+
* Second Item
622538
623-
* executeCommand("someServerScript.ps1","bash someServerScript.sh", {"asynchronous": true, "args":["-port 8080"] },{"port":8080 , "startupTime": 20, "path": "some/path/", "interval": 2})
624-
Starting a server in a new terminal. You have to specify the port for testing, the other parameters are optional. The startupTime can specify how long the runner will wait for a response from the server process and with interval you can set the frequenzy for the server testing. The path is the subpath from your server that should be reached.
539+
Link:
540+
The tutorials repository can be found https://github.com/devonfw-tutorials/tutorials/issues[here].
541+
```
542+
##### Note:
543+
1. You should avoid using any command inside any text file for which you want to display content. This will cause problems with the console runner and the tests.
625544

626545
***
627546

@@ -760,3 +679,89 @@ will run "git clone https://github.com/[GitHub-name]/[playbook-name]" and checko
760679
Learn more about the workspace directory and working directory on [Structure](https://github.com/devonfw-tutorials/tutorial-compiler/wiki/Structure)
761680

762681
***
682+
683+
## Other Functions <a name="otherFunctions"></a>
684+
685+
### i. addSetupScript <a name="addSetupScript"></a>
686+
This function is used to add a script which is executed on startup of the tutorial.
687+
#### Parameter:
688+
This function consist of two parameters
689+
1. First parameter:
690+
- **Required**
691+
- **Type**- String
692+
- **Description**- Path of the script (Linux). Relative to the playbook directory.
693+
2. Second parameter:
694+
- **Required**
695+
- **Type**- String
696+
- **Description**- Path of the script (Windows). Relative to the playbook directory.
697+
698+
#### Example:
699+
* addSetupScript("assets/createProjectScript.sh", "assets/createProjectScript.ps1")
700+
701+
##### Note:
702+
1. For Katacoda, only first parameter is required.
703+
2. The script will run in the background while starting the tutorial. Katacoda user will have to wait till the script execution is in process. Once it is done it, Katacoda user will get the message and then command prompt will be available to Katacoda user.
704+
705+
***
706+
707+
708+
### ii. executeCommand <a name="executeCommand"></a>
709+
This function is used when you want to use a bash (or powershell/cmd on windows) command.
710+
711+
#### Parameter:
712+
This function consists of four parameters.
713+
714+
1. First parameter:
715+
- **Required**
716+
- **Type**- String
717+
- **Description**-It contains the input which is a command. The command that will be executed on Windows.
718+
719+
2. Second parameter:
720+
- **Required**
721+
- **Type**- String
722+
- **Description**-It contains the input which is a command. The command that will be executed on Linux.
723+
724+
3. Third parameter:
725+
- **Required**
726+
- **Type**- JSON object
727+
- **Description**- This parameter consist of three attribute. It is a JSON object with optional fields
728+
* First attribute: (Optional) Directory where the command will be executed, if not in current directory (relative to workspace)
729+
Example: {"dir": string}
730+
* Second attribute: (Optional) Synchronous or asynchronous process. Use asynchronous when starting a server. Default is synchronous.
731+
Example: {"asynchronous": boolean}
732+
* Third attribute: (Optional) Array of arguments
733+
Example: {"args": string[]}
734+
735+
4. Fourth parameter:
736+
- **Required**
737+
- **Type**- JSON object
738+
- **Description**- This parameter consist of three attributes which are the assertion information. Assertion information is needed if you start a server to check server availability. Only required when you start a asynchronous server. This parameter is only needed when the command is an asynchronous command.
739+
* First attribute: "startupTime" which is the time in seconds to wait before checking if the server is running
740+
* Second attribute: "port" which is the port number on which the server is running
741+
* Third attribute: "path" which is the path to the URL path on which is checked if the server is running
742+
743+
#### Commands:
744+
It is needed to pass a command for Windows and also for Linux-based systems because both systems will always be tested.
745+
746+
##### Assertion information
747+
startupTime = Time in seconds to wait before checking if the server is running
748+
port: Port on which the server is running
749+
path: The URL path on which is checked if the server is running
750+
interval: The availability of the server is checked in the given interval
751+
* (Required) port: will throw error if no port is given.
752+
* (Optional) path: subpath which should be pinged, i.e: if localhost:8081/jumpthequeue should be checked path should be "jumpthequeue". DEFAULT: ""
753+
* (Optional) interval: interval in seconds in which the server should be pinged until it is available or timeouted. DEFAULT: 5 seconds
754+
* (Optional) startupTime: seconds until a timeout will occur and an error will be thrown. DEFAULT: 10 minutes
755+
756+
#### Example:
757+
758+
* executeCommand("node", "node" ,{"args": ["-v"]})
759+
Will create a command for executing node -v .
760+
761+
* executeCommand("somePollingScript.ps1","bash somePollingScript.sh", {"dir": "data/setup", "args": ["--params 5"]})
762+
Will create a command to execute the script in the directory with the parameter --params 5 and in the current command prompt. The command prompt will be blocked until you stop the script.
763+
764+
* executeCommand("someServerScript.ps1","bash someServerScript.sh", {"asynchronous": true, "args":["-port 8080"] },{"port":8080 , "startupTime": 20, "path": "some/path/", "interval": 2})
765+
Starting a server in a new terminal. You have to specify the port for testing, the other parameters are optional. The startupTime can specify how long the runner will wait for a response from the server process and with interval you can set the frequenzy for the server testing. The path is the subpath from your server that should be reached.
766+
767+
***

0 commit comments

Comments
 (0)