doc(faq): add technical FAQ section for commonly asked questions (#624)

* doc(faq): add technical FAQ section for commonly asked questions

* fix: new python script plugin

content/docs/05.developer-guide/01.flow.md

@@ -54,10 +54,10 @@ You can add arbitrary `labels` to your flows to sort them on multiple dimensions
 
 You can also define `taskDefaults` inside your flow. This is a list of default task properties that will be applied to each task of a certain type inside your flow. Task defaults can be handy to avoid repeating the same value for a task property in case the same task type is used multiple times in the same flow.
 
-### Variables 
+### Variables
 You can set flow variables that will be accessible by each task using `{{ vars.key }}`. Flow `variables` is a map of key/value pairs.
 
-### List of tasks 
+### List of tasks
 
 The most important part of a flow is the list of tasks that will be run sequentially when the flow is executed.
 
@@ -91,38 +91,58 @@ The following flow properties can be set.
 You can add task defaults to avoid repeating task properties on multiple occurrences of the same task in a `taskDefaults` properties. For example:
 
 ```yaml
-id: python_test
-namespace: test
+id: api_python_sql
+namespace: dev
 
 tasks:
-
-  - id: hello_from_docker
-    type: io.kestra.core.tasks.scripts.Python
-    inputFiles:
-      main.py: |
-        print("Hello World!")
-
-  - id: hello_from_docker_2
-    type: io.kestra.core.tasks.scripts.Python
+  - id: api
+    type: io.kestra.plugin.fs.http.Request
+    uri: https://dummyjson.com/products
+
+  - id: hello
+    type: io.kestra.plugin.scripts.python.Script
+    docker:
+      image: python:slim
+    script: |
+      print("Hello World!")
+
+  - id: python
+    type: io.kestra.plugin.scripts.python.Script
+    docker:
+      image: python:slim
+    beforeCommands:
+      - pip install polars
+    warningOnStdErr: false
+    script: |
+      import polars as pl
+      data = {{outputs.api.body | jq('.products') | first}}
+      df = pl.from_dicts(data)
+      df.glimpse()
+      df.select(["brand", "price"]).write_csv("{{outputDir}}/products.csv")
+
+  - id: sql_query
+    type: io.kestra.plugin.jdbc.duckdb.Query
     inputFiles:
-      main.py: |
-        print("Hello World again!")
+      in.csv: "{{ outputs.python.outputFiles['products.csv'] }}"
+    sql: |
+      SELECT brand, round(avg(price), 2) as avg_price
+      FROM read_csv_auto('{{workingDir}}/in.csv', header=True)
+      GROUP BY brand
+      ORDER BY avg_price DESC;
+    store: true
 
 taskDefaults:
-  - type: io.kestra.core.tasks.scripts.Python
+  - type: io.kestra.plugin.scripts.python.Script
     values:
-      virtualEnv: false
-      commands:
-        - python main.py
       runner: DOCKER
-      dockerOptions:
-        image: custom_python
-        pullImage: false
+      docker:
+        image: python:slim
+        pullPolicy: ALWAYS # NEVER to use a local image
 ```
 
 Here, we avoid repeating Docker and Python configurations in each task by directly setting those within the `taskDefaults` property. This approach helps to streamline the configuration process and reduce the chances of errors caused by inconsistent settings across different tasks.
 
-Note that when you move some required task attributes into the `taskDefaults` property, the code editor within the UI will complain that the required task argument is missing. The editor shows this message because `taskDefaults` are resolved at runtime and the editor is not aware of those default attributes until you run your flow. As long as `taskDefaults` contains the relevant arguments, you can save the flow and ignore the warning displayed in the editor. 
+Note that when you move some required task attributes into the `taskDefaults` property, the code editor within the UI will complain that the required task argument is missing. The editor shows this message because `taskDefaults` are resolved at runtime and the editor is not aware of those default attributes until you run your flow. As long as `taskDefaults` contains the relevant arguments, you can save the flow and ignore the warning displayed in the editor.
 
 ![taskDefaultsWarning](/docs/developer-guide/flow/warning.png)
 
@@ -140,10 +160,6 @@ You can add a `description` property on:
 - [Listeners](./13.listeners.md)
 - [Triggers](./08.triggers/index.md)
 
-All descriptions will be visible on the UI:
-
-![Flow list](/docs/developer-guide/flow/docs-ui-1.png)
-
-![Topology](/docs/developer-guide/flow/docs-ui-2.png)
+All markdown descriptions will be rendered in the UI.
 
-![Trigger details](/docs/developer-guide/flow/docs-ui-3.png)
+![description](/docs/developer-guide/flow/description.png)

content/docs/16.faq/flows.md

@@ -0,0 +1,105 @@
+---
+title: Flows FAQ
+---
+
+## Where does kestra store flows?
+
+Flows are stored in a serialized format directly **in the Kestra backend database**.
+
+The easiest way to add new flows is to add them directly from the [Kestra UI](../04.user-interface-guide/index.md). You can also use the [CI/CD](../05.developer-guide/13.cicd/index.md) to add flows automatically after a pull request is merged to a given Git branch.
+
+To see how flows are represented in a file structure, you can leverage the `_flows` directory in the [Namespace Files](../05.developer-guide/namespace-files.md) editor.
+
+### How to load flows at server startup?
+
+If you want to load a given local directory of flows to be loaded into Kestra (e.g. during local development), you can use the `-f` or `--flow-path` flag when starting Kestra:
+
+```bash
+./kestra server standalone -f /path/to/flows
+```
+
+That path should point to a directory containing YAML files with the flow definition. These files will be loaded to the kestra repository at startup. Kestra will make sure to add flows to the right namespace, as declared in the flow YAML definition.
+
+For more information about the Kestra server CLI, check the [Administrator Guide](../09.administrator-guide/04.servers.md) section.
+
+### Can I sync a local flows directory to be continuously loaded into Kestra?
+At the time of writing, there is no syncing of a flows directory to Kestra. However, we are aware of that need and we are working on a solution. You can follow up in [this GitHub issue](https://github.com/kestra-io/kestra/issues/2403).
+
+---
+
+## How to trigger a flow?
+
+There are multiple ways to trigger a flow.
+
+### The `Execute` button in the UI
+
+You can trigger a flow manually from the [Kestra UI](../04.user-interface-guide/index.md).
+
+### Triggers
+
+You can add a **[Schedule trigger](../05.developer-guide/08.triggers/01.schedule.md)** to automatically launch a flow execution at a regular time interval.
+
+Alternatively, you can add a **[Flow trigger](../05.developer-guide/08.triggers/02.flow.md)** to automatically launch a flow execution when another flow execution is completed. This pattern is particularly helpful when you want to:
+- Implement a centralized namespace-level error handling strategy, e.g. to send a notification when any flow execution fails in a production namespace. Check the [Alerting & Monitoring](../09.administrator-guide/03.monitoring/index.md) section for more details.
+- Decouple your flows by following an event-driven pattern, in a backwards direction (_backwards because the flow is triggered by the completion of another flow; this is in contrast to the [subflow pattern](https://kestra.io/plugins/core/tasks/flows/io.kestra.core.tasks.flows.flow), where a parent flow starts the execution of child flows and waits for the completion of each of them_).
+
+Lastly, you can use the **[Webhook trigger](../05.developer-guide/08.triggers/03.webhook.md)** to automatically launch a flow execution when a given HTTP request is received. You can leverage the `{{ trigger.body }}` variable to access the request body and the `{{ trigger.headers }}` variable to access the request headers in your flow.
+
+### API calls
+
+You can trigger a flow execution by calling the [API](../12.api-guide/index.md) directly. This is useful when you want to trigger a flow execution from another application or service.
+
+Let's use the following flow as example:
+
+```yaml
+id: hello-world
+namespace: dev
+
+inputs:
+  - name: greeting
+    type: STRING
+    defaults: hello
+
+tasks:
+  - id: hello
+    type: io.kestra.core.tasks.log.Log
+    message: "{{ inputs.greeting }}, kestra team wishes you a great day!"
+```
+
+Assuming that you run Kestra locally, you can trigger a flow execution by calling the ``executions/trigger`` endpoint:
+
+```bash
+curl -X POST http://localhost:8080/api/v1/executions/trigger/dev/hello-world
+```
+
+The above command will trigger an execution of the latest revision of the `hello-world` flow from the `dev` namespace. If you want to trigger an execution for a specific revision, you can use the `revision` query parameter:
+
+```bash
+curl -X POST http://localhost:8080/api/v1/executions/trigger/dev/hello-world?revision=6
+```
+
+You can also trigger a flow execution with inputs by passing the `inputs` query parameter:
+
+```bash
+curl -X POST http://localhost:8080/api/v1/executions/trigger/dev/hello-world -F greeting="hey there"
+```
+
+
+### Python SDK
+
+You can also launch a flow using the [kestra pip package](../05.developer-guide/12.python-sdk.md). This is useful when you want to trigger a flow execution from a Python application or service.
+
+First, install the package:
+
+```bash
+pip install kestra
+```
+
+Then, you can trigger a flow execution by calling the `execute()` method. Here is an exmaple for the same `hello-world` flow in the namespace `dev` as above:
+
+```python
+from kestra import Flow
+flow = Flow()
+flow.execute('dev', 'hello-world', {'greeting': 'hello from Python'})
+```
+

content/docs/16.faq/index.md

@@ -0,0 +1,9 @@
+---
+title: ❓ FAQ
+---
+
+This section covers frequently asked questions about Kestra.
+
+
+<ChildTableOfContents />
+