Merge pull request #85 from kestra-io/docs/input_outputs_ruby_julia

doc: improve examples and new properties

plugin-script-julia/src/main/java/io/kestra/plugin/scripts/julia/Commands.java

@@ -21,32 +21,30 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Execute one or more Julia commands from the Command Line Interface."
+    title = "Execute Julia scripts from the Command Line Interface."
 )
 @Plugin(examples = {
     @Example(
         full = true,
-        title = "Install package, create a julia script and execute it",
+        title = "Create a Julia script, install required packages and execute it. Note that instead of defining the script inline, you could create the Julia script in the embedded VS Code editor and point to its location by path. If you do so, make sure to enable namespace files by setting the `enabled` flag of the `namespaceFiles` property to `true`.",
         code = """
-            id: "local-files"
-            namespace: "io.kestra.tests"
-
+            id: "script"
+            namespace: "dev"
             tasks:
-              - id: workingDir
-                type: io.kestra.core.tasks.flows.WorkingDirectory
-                tasks:
-                - id: inputFiles
-                  type: io.kestra.core.tasks.storages.LocalFiles
-                  inputs:
-                    main.js: |
-                      const colors = require("colors");
-                      console.log(colors.red("Hello"));
-                - id: bash
-                  type: io.kestra.plugin.scripts.julia.Commands
-                  beforeCommands:
-                    - npm install colors
-                  commands:
-                    - julia main.jl
+              - id: bash
+                type: io.kestra.plugin.scripts.julia.Commands
+                warningOnStdErr: false
+                inputFiles:
+                  main.jl: |
+                    using DataFrames, CSV
+                    df = DataFrame(Name = ["Alice", "Bob", "Charlie"], Age = [25, 30, 35])
+                    CSV.write("output.csv", df)
+                outputFiles:
+                  - output.csv
+                beforeCommands:
+                  - julia -e 'using Pkg; Pkg.add("DataFrames"); Pkg.add("CSV")'
+                commands:
+                  - julia main.jl
             """
     )
 })

plugin-script-julia/src/main/java/io/kestra/plugin/scripts/julia/Script.java

@@ -29,12 +29,24 @@
 )
 @Plugin(examples = {
     @Example(
-        title = "Create a julia script and execute it",
-        code = {
-            "script: |",
-            "  const colors = require(\"colors\");",
-            "  console.log(colors.red(\"Hello\"));",
-        }
+        full = true,
+        title = "Create a Julia script, install required packages and execute it. Note that instead of defining the script inline, you could create the Julia script in the embedded VS Code editor and read its content using the `{{ read('your_script.jl') }}` function.",
+        code = """
+            id: "script"
+            namespace: "dev"
+            tasks:
+              - id: bash
+                type: io.kestra.plugin.scripts.julia.Script
+                warningOnStdErr: false
+                script: |
+                  using DataFrames, CSV
+                  df = DataFrame(Name = ["Alice", "Bob", "Charlie"], Age = [25, 30, 35])
+                  CSV.write("output.csv", df)
+                outputFiles:
+                  - output.csv
+                beforeCommands:
+                  - julia -e 'using Pkg; Pkg.add("DataFrames"); Pkg.add("CSV")'
+            """
     )
 })
 public class Script extends AbstractExecScript {
@@ -49,7 +61,7 @@ public class Script extends AbstractExecScript {
     protected DockerOptions docker = DockerOptions.builder().build();
 
     @Schema(
-        title = "The inline script content. This property is intended for the script file's content as a (multiline) string, not a path to a file. To run a command from a file such as `bash myscript.sh` or `python myscript.py`, use the `Commands` task instead."
+        title = "The inline script content. This property is intended for the script file's content as a (multiline) string, not a path to a file. To run a command such as `julia myscript.jl`, use the `Commands` task instead."
     )
     @PluginProperty(dynamic = true)
     @NotNull
@@ -81,7 +93,6 @@ public ScriptOutput run(RunContext runContext) throws Exception {
         );
 
         return commands
-            .addEnv(Map.of("PYTHONUNBUFFERED", "true"))
             .withCommands(commandsArgs)
             .run();
     }

plugin-script-node/src/main/java/io/kestra/plugin/scripts/node/Commands.java

@@ -21,32 +21,26 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Execute one or more Node commands from the Command Line Interface."
+    title = "Execute one or more Node commands from the Command Line Interface. Note that instead of adding the script using the `inputFiles` property, you could also add the script from the embedded VS Code editor and point to its location by path. If you do so, make sure to enable namespace files by setting the `enabled` flag of the `namespaceFiles` property to `true`."
 )
 @Plugin(examples = {
     @Example(
         full = true,
-        title = "Install package, create a node script and execute it",
+        title = "Install required npm packages, create a Node script and execute it.",
         code = """
-            id: "local-files"
-            namespace: "io.kestra.tests"
-
+            id: node
+            namespace: dev
             tasks:
-              - id: workingDir
-                type: io.kestra.core.tasks.flows.WorkingDirectory
-                tasks:
-                - id: inputFiles
-                  type: io.kestra.core.tasks.storages.LocalFiles
-                  inputs:
-                    main.js: |
-                      const colors = require("colors");
-                      console.log(colors.red("Hello"));
-                - id: bash
-                  type: io.kestra.plugin.scripts.node.Commands
-                  beforeCommands:
-                    - npm install colors
-                  commands:
-                    - node main.js
+              - id: node_script
+                type: io.kestra.plugin.scripts.node.Commands
+                inputFiles:
+                  main.js: |
+                    const colors = require("colors");
+                    console.log(colors.red("Hello"));
+                beforeCommands:
+                  - npm install colors
+                commands:
+                  - node main.js
             """
     )
 })

plugin-script-node/src/main/java/io/kestra/plugin/scripts/node/Script.java

@@ -41,7 +41,9 @@
     @Example(
         full = true,
         title = """
-        If you want to generate files in your script to make them available for download and use in downstream tasks, you can leverage the `{{outputDir}}` variable. Files stored in that directory will be persisted in Kestra's internal storage. To access this output in downstream tasks, use the syntax `{{outputs.yourTaskId.outputFiles['yourFileName.fileExtension']}}`.
+        If you want to generate files in your script to make them available for download and use in downstream tasks, you can leverage the `{{outputDir}}` variable. Files stored in that directory will be persisted in Kestra's internal storage. To access this output in downstream tasks, use the syntax `{{outputs.yourTaskId.outputFiles['yourFileName.fileExtension']}}`. 
+        
+        Alternatively, instead of the `{{outputDir}}` variable, you could use the `outputFiles` property to output files from your script. You can access those files in downstream tasks using the same syntax `{{outputs.yourTaskId.outputFiles['yourFileName.fileExtension']}}`, and you can download the files from the UI's Output tab.
         """,
         code = """
             id: nodeJS

plugin-script-powershell/src/main/java/io/kestra/plugin/scripts/powershell/Commands.java

@@ -23,29 +23,23 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Execute one or more PowerShell commands."
+    title = "Execute one or more PowerShell commands. Note that instead of adding the script using the `inputFiles` property, you could also add the script from the embedded VS Code editor and point to its location by path. If you do so, make sure to enable namespace files by setting the `enabled` flag of the `namespaceFiles` property to `true`."
 )
 @Plugin(examples = {
     @Example(
         full = true,
-        title = "Create a PowerShell script and execute it",
+        title = "Create a PowerShell script and execute it.",
         code = """
-            id: "local-files"
-            namespace: "io.kestra.tests"
-
+            id: powershell
+            namespace: dev
             tasks:
-              - id: workingDir
-                type: io.kestra.core.tasks.flows.WorkingDirectory
-                tasks:
-                - id: inputFiles
-                  type: io.kestra.core.tasks.storages.LocalFiles
-                  inputs:
-                    main.ps1: |
-                      Get-ChildItem | Format-List
-                - id: bash
-                  type: io.kestra.plugin.scripts.powershell.Commands
-                  commands:
-                    - pwsh main.ps1
+              - id: powershell_script
+                type: io.kestra.plugin.scripts.powershell.Commands
+                inputFiles:
+                  main.ps1: |
+                    Get-ChildItem | Format-List
+                commands:
+                  - pwsh main.ps1
             """
     )
 })

plugin-script-python/src/main/java/io/kestra/plugin/scripts/python/Commands.java

@@ -26,6 +26,44 @@
     title = "Execute one or more Python scripts from a Command Line Interface."
 )
 @Plugin(examples = {
+    @Example(
+        full = true,
+        title = """
+        Execute a Python script in a Conda virtual environment. First, add the following script in the embedded VS Code editor and name it `etl_script.py`:
+          
+        ```python
+        import argparse
+
+        parser = argparse.ArgumentParser()
+
+        parser.add_argument("--num", type=int, default=42, help="Enter an integer")
+
+        args = parser.parse_args()
+        result = args.num * 2
+        print(result)
+        ```
+          
+        Then, make sure to set the `enabled` flag of the `namespaceFiles` property to `true` to enable [namespace files](https://kestra.io/docs/developer-guide/namespace-files).           
+        ```
+
+        This flow uses a `PROCESS` runner and Conda virtual environment for process isolation and dependency management. However, note that, by default, Kestra runs tasks in a Docker container (i.e. a `DOCKER` runner), and you can use the `docker` property to customize many options, such as the Docker image to use.
+        """,
+        code = """     
+id: python_venv
+namespace: dev
+
+tasks:
+  - id: hello
+    type: io.kestra.plugin.scripts.python.Commands
+    namespaceFiles:
+      enabled: true
+    runner: PROCESS
+    beforeCommands:
+      - conda activate myCondaEnv
+    commands:
+      - python etl_script.py
+                """
+        ),  
     @Example(
         full = true,
         title = "Execute a Python script from Git in a Docker container and output a file",
@@ -52,10 +90,7 @@
         commands:
           - python scripts/etl_script.py
           - python scripts/generate_orders.py
-      
-      - id: outputFile
-        type: io.kestra.core.tasks.storages.LocalFiles
-        outputs:
+        outputFiles:
           - orders.csv
 
   - id: loadCsvToS3
@@ -68,23 +103,6 @@
     from: "{{outputs.outputFile.uris['orders.csv']}}"
                 """
         ),
-    @Example(
-        full = true,
-        title = "Execute a Python script in a Conda virtual environment",
-        code = """     
-id: localPythonScript
-namespace: dev
-
-tasks:
-  - id: hello
-    type: io.kestra.plugin.scripts.python.Commands
-    runner: PROCESS
-    beforeCommands:
-      - conda activate myCondaEnv
-    commands:
-      - python /Users/you/scripts/etl_script.py
-                """
-        ),
     @Example(
         full = true,
         title = "Execute a Python script on a remote worker with a GPU",
@@ -119,23 +137,17 @@
         url: https://github.com/kestra-io/examples
         branch: main
 
-      - id: local
-        type: io.kestra.core.tasks.storages.LocalFiles
-        inputs:
-          data.csv: "{{ trigger.objects | jq('.[].uri') | first }}"
-
       - id: python
         type: io.kestra.plugin.scripts.python.Commands
+        inputFiles:
+          data.csv: "{{ trigger.objects | jq('.[].uri') | first }}"
         description: this script reads a file `data.csv` from S3 trigger
         docker:
           image: ghcr.io/kestra-io/pydata:latest
         warningOnStdErr: false
         commands:
           - python scripts/clean_messy_dataset.py
-
-      - id: output
-        type: io.kestra.core.tasks.storages.LocalFiles
-        outputs:
+        outputFiles:
           - "*.csv"
           - "*.parquet"
 
@@ -188,9 +200,10 @@
                   }
               }
             }
+
       - id: output
         type: io.kestra.core.tasks.storages.LocalFiles
-        outputs:
+        outputFiles:
           - "*.csv"
           - "*.parquet"
                 """
@@ -199,31 +212,25 @@
         full = true,
         title = "Create a python script and execute it in a virtual environment",
         code = """
-            id: "local-files"
-            namespace: "io.kestra.tests"
-
+            id: "script_in_venv"
+            namespace: "dev"
             tasks:
-              - id: workingDir
-                type: io.kestra.core.tasks.flows.WorkingDirectory
-                tasks:
-                - id: inputFiles
-                  type: io.kestra.core.tasks.storages.LocalFiles
-                  inputs:
-                    main.py: |
-                      import requests
-                      from kestra import Kestra
+              - id: bash
+                type: io.kestra.plugin.scripts.python.Commands
+                inputFiles:
+                  main.py: |
+                    import requests
+                    from kestra import Kestra
 
-                      response = requests.get('https://google.com')
-                      print(response.status_code)
-                      Kestra.outputs({'status': response.status_code, 'text': response.text})
-                - id: bash
-                  type: io.kestra.plugin.scripts.python.Commands
-                  beforeCommands:
-                    - python -m venv venv
-                    - . venv/bin/activate
-                    - pip install requests kestra > /dev/null
-                  commands:
-                    - python main.py
+                    response = requests.get('https://google.com')
+                    print(response.status_code)
+                    Kestra.outputs({'status': response.status_code, 'text': response.text})                    
+                beforeCommands:
+                  - python -m venv venv
+                  - . venv/bin/activate
+                  - pip install requests kestra > /dev/null
+                commands:
+                  - python main.py
             """
     )        
 })

plugin-script-python/src/main/java/io/kestra/plugin/scripts/python/Script.java

@@ -57,7 +57,7 @@
             code = {
                 "script: |",
                 "   f = open(\"{{outputDir}}/myfile.txt\", \"a\")",
-                "   f.write(\"I can output files from my script!\")",
+                "   f.write(\"Hello from a Kestra task!\")",
                 "   f.close()"
             }
         ),