Workflow as code added to comparaison + cleaned VS Code doc

hcourdent · hcourdent · commit 145a2e56a476 · 2024-03-11T12:44:36.000+01:00
diff --git a/docs/assets/compared_to/windmill_compared_prefect.png b/docs/assets/compared_to/windmill_compared_prefect.png
diff --git a/docs/assets/compared_to/windmill_compared_prefect.png.webp b/docs/assets/compared_to/windmill_compared_prefect.png.webp
diff --git a/docs/cli_local_dev/1_vscode-extension/index.mdx b/docs/cli_local_dev/1_vscode-extension/index.mdx
@@ -6,15 +6,7 @@ The Windmill VS Code extension allows you to build scripts and flows in the comf
 
 ![VS Code Extension](../../../blog/2023-11-20-vscode/vscode_extension.png 'VS Code Extension')
 
-The extension can be used in particular from a [repository synchronized to a Windmill instance](../../advanced/3_cli/sync.mdx) to [develop scripts & flows locally](../../advanced/4_local_development/index.mdx) while keeping them synced to your workspace.
-
-<div className="grid grid-cols-2 gap-6 mb-4">
-	<DocCard
-		title="Command-Line Interface - Sync"
-		description="Sync with a Windmill workspace from Windmill CLI."
-		href="/docs/advanced/cli"
-	/>
-</div>
+The extension can be used in particular from a repository synchronized to a Windmill instance to [develop scripts & flows locally](../../advanced/4_local_development/index.mdx) while keeping them synced to your workspace.
 
 <iframe
 	style={{ aspectRatio: '16/9' }}
@@ -56,7 +48,7 @@ To run scripts locally, see [Run Locally](../../advanced/4_local_development/run
 
 ## Installation
 
-1. First of all, have your workspace synced locally with [Windmill CLI](../../advanced/3_cli/index.mdx).
+First of all, have your workspace synced locally with [Windmill CLI](../../advanced/3_cli/index.mdx).
 
 ![Local workspace](../../../blog/2023-11-20-vscode/local_workspace.png.webp)
 
@@ -74,6 +66,18 @@ In the settings menu, set the remote url, workspace name and [token](../../core_
 
 3. From any script file, use `> Windmill: Run preview in the current editor` or Ctrl+Enter and Shift+Enter to generate the UI preview (provided that the script meets the [few rules](../../core_concepts/13_json_schema_and_parsing/index.md#json-schema-in-windmill) required by Windmill).
 
+All details to set up the workspace folder:
+
+<div className="grid grid-cols-2 gap-6 mb-4">
+	<DocCard
+		title="Setting up the workspace folder"
+		description="Developing Windmill scripts and flows from your favorite IDE is made easy by using Windmill CLI."
+		href="/docs/advanced/local_development#setting-up-the-workspace-folder"
+	/>
+</div>
+
+## Actions
+
 The preview & run will work for any script meeting the specific language requirements (main function, imports) and being named with the dedicated file extension (.py, .go etc.). For scripts in Bun, name the file \[name\].bun.ts, ".ts" being by default Deno.
 
 The extension will split your screen and display a panel. That panel will update automatically based on the edited document on the left.
@@ -83,34 +87,40 @@ The extension will split your screen and display a panel. That panel will update
 
 In particular:
 
-## Test scripts, flows and flows steps from VS Code
+### Test scripts, flows and flows steps
+
+Once you have your scripts and flows locally (either pulled from a remote workspace or created from scratch), you can test them directly from VS Code.
 
 <video
 	className="border-2 rounded-xl object-cover w-full h-full dark:border-gray-800"
 	autoPlay
-	loop
+	controls
 	src="/videos/vs_code_tour.mp4"
 />
 
-## Editing the YAML definition of a flow instantly updates the rendered graph
+### Update UI from YAML
+
+Editing the YAML definition of a flow instantly updates the rendered graph
 
 <video
 	className="border-2 rounded-xl object-cover w-full h-full dark:border-gray-800"
 	autoPlay
-	loop
+	controls
 	src="/videos/ui_to_yaml.mp4"
 />
 
-## Editing the flow from the UI immediately modifies the YAML definition
+### Update YAML from UI
+
+Editing the flow from the UI immediately modifies the YAML definition
 
 <video
 	className="border-2 rounded-xl object-cover w-full h-full dark:border-gray-800"
 	autoPlay
-	loop
+	controls
 	src="/videos/yaml_to_ui.mp4"
 />
 
-## Infer lockfile or Use current lockfile
+### Infer lockfile or Use current lockfile
 
 With this toggle, you can choose to use the metadata lockfile instead of inferring them directly from the script.
 
diff --git a/docs/compared_to/peers.mdx b/docs/compared_to/peers.mdx
@@ -32,7 +32,7 @@ Airflow and Temporal are the golden standards. They are very good, battle-tested
 
 <br />
 
-Those frameworks are a great source of inspiration for us but we bring a more principled and more opinionated approach so that one can focus on writing scripts rather than becoming a workflow engine expert. The goal of Windmill is to bring the benefits of those workflow engines in a more accessible package that is fit not just for data engineers but for hybrid teams made of data scientist, ops, and software engineers with standard scripts in Python/Typescript/Go/Bash and low-code builder for the graph itself the common denominator, without any sacrifice on performance (and actually we run workflows faster than those frameworks, more on that in [1]), features, scalability/reliability and by improving the debuggability and developer experience of those.
+Those frameworks are a great source of inspiration for us but we bring a more principled and more opinionated approach so that one can focus on writing scripts rather than becoming a workflow engine expert. The goal of Windmill is to bring the benefits of those workflow engines in a more accessible package that is fit not just for data engineers but for hybrid teams made of data scientist, ops, and software engineers with standard scripts in Python/Typescript/Go/Bash and low-code builder for the graph itself the common denominator, without any sacrifice on performance (and actually we run workflows faster than those frameworks, more on that in [1]), features, scalability/reliability and by improving the debuggability and developer experience of those. It is also possible to define [workflows-as-code](../core_concepts/31_workflows_as_code/index.mdx), in the same way as Prefect or Airflow (writing a program that defines the jobs and their dependencies, and then execute that program).
 
 <br />
 
diff --git a/docs/compared_to/prefect.mdx b/docs/compared_to/prefect.mdx
@@ -75,29 +75,33 @@ We could also mention [storage of configuration](../core_concepts/3_resources_an
 
 ![Prefect features](../assets/compared_to/prefect_features.png.webp 'Prefect features')
 
-The difference between Prefect and Windmill lies in the method of building flows.
-
 Prefect is heavily code-based. Everything is and can only be defined in Python. The steps and their configurations are defined by code:
 
 ![Prefect flow](../assets/compared_to/flow_prefect.png.webp 'Prefect flow')
 
-> [Flow](#benchmark-1) _Given a GitHub repository, logs the number of stargazers and contributors for that repo_ on Prefect.
+> [Flow](#benchmark-1) "_Given a GitHub repository, logs the number of stargazers and contributors for that repo_" on Prefect.
 
 <br />
 
-In Windmill, the steps are also code-based but built from scripts ([TypeScript](../getting_started/0_scripts_quickstart/1_typescript_quickstart/index.mdx), [Python](../getting_started/0_scripts_quickstart/2_python_quickstart/index.mdx), [Go](../getting_started/0_scripts_quickstart/3_go_quickstart/index.mdx), [Bash](../getting_started/0_scripts_quickstart/4_bash_quickstart/index.mdx), [SQL](../getting_started/0_scripts_quickstart/5_sql_quickstart/index.mdx) ...). Users can write the code directly, choose a script from the workspace, the community library [WindmillHub](https://hub.windmill.dev/), or have it [generated with AI](#windmill-ai). Each script can be saved with [permissions](../core_concepts/16_roles_and_permissions/index.mdx) set from the workspace.
+Windmill offers both low-code and code-based solutions.
+
+![Windmill compared to Prefect](../assets/compared_to/windmill_compared_prefect.png 'Windmill compared to Prefect')
+
+### Flow Editor
+
+In Windmill's [Flow Editor](../flows/1_flow_editor.mdx), the steps are also code-based but built from scripts ([TypeScript](../getting_started/0_scripts_quickstart/1_typescript_quickstart/index.mdx), [Python](../getting_started/0_scripts_quickstart/2_python_quickstart/index.mdx), [Go](../getting_started/0_scripts_quickstart/3_go_quickstart/index.mdx), [Bash](../getting_started/0_scripts_quickstart/4_bash_quickstart/index.mdx), [SQL](../getting_started/0_scripts_quickstart/5_sql_quickstart/index.mdx) ...). Users can write the code directly, choose a script from the workspace, the community library [WindmillHub](https://hub.windmill.dev/), or have it [generated with AI](#windmill-ai). Each script can be saved with [permissions](../core_concepts/16_roles_and_permissions/index.mdx) set from the workspace.
 
 The structuring of the flow and the configurations for each step are defined from a User Interface. With a _code when you need_ mindset, the user can navigate the flow editor in low-code.
 
 ![Windmill flow](../assets/compared_to/flow_windmill.png.webp 'Windmill flow')
 
-> [Flow](#benchmark-1) _Given a GitHub repository, logs the number of stargazers and contributors for that repo_ on Windmill.
+> [Flow](#benchmark-1) "_Given a GitHub repository, logs the number of stargazers and contributors for that repo_" on Windmill.
 
 <br />
 
 In particular, Windmill [generates automatically UIs](../core_concepts/6_auto_generated_uis/index.mdx) for flows and steps and lets users [test](../core_concepts/23_instant_preview/index.mdx) flows, steps or flow until a given step, from the UI.
 
-Flows can be [defined visually / YAML](../advanced/4_local_development/index.mdx) on a local environment. In particular, Windmill has a VS Code extension to edit from your code editor scripts and workflows-as-code.
+Flows can be [defined visually / YAML](../advanced/4_local_development/index.mdx) on a local environment. In particular, Windmill has a [VS Code extension](../cli_local_dev/1_vscode-extension/index.mdx) to edit from your code editor scripts flows YAML.
 
 <div className="grid grid-cols-2 gap-6 mb-4">
 	<DocCard
@@ -107,7 +111,13 @@ Flows can be [defined visually / YAML](../advanced/4_local_development/index.mdx
 	/>
 </div>
 
-![Windmill compared to Prefect](../assets/compared_to/windmill_compared_prefect.png.webp 'Windmill compared to Prefect')
+### Workflows as Code
+
+[Flows](#flow-editor) are not the only way to write distributed programs that execute distinct jobs. Another approach is to write a program that defines the jobs and their dependencies, and then execute that program. This is known as [workflows as code](../core_concepts/31_workflows_as_code/index.mdx).
+
+![Script in python executing workflow as code](../core_concepts/31_workflows_as_code/python_editor.png "Script in python executing workflow as code")
+
+Windmill supports defining workflows as code in a single script in both [Python](../getting_started/0_scripts_quickstart/2_python_quickstart/index.mdx) and [TypeScript](../getting_started/0_scripts_quickstart/1_typescript_quickstart/index.mdx) using intuitive and lightweight syntax.
 
 ## Triggers
 
diff --git a/docs/core_concepts/31_workflows_as_code/index.mdx b/docs/core_concepts/31_workflows_as_code/index.mdx
@@ -5,11 +5,11 @@ import TabItem from '@theme/TabItem';
 
 [Flows](../../flows/1_flow_editor.mdx) are not the only way to write distributed programs that execute distinct jobs. Another approach is to write a program that defines the jobs and their dependencies, and then execute that program. This is known as workflows as code.
 
-![Script in python executing workflow as code](python_editor.png "Script in python executing workflow as code")
+![Script in python executing workflow as code](./python_editor.png "Script in python executing workflow as code")
 
 One way of doing this is to use the [API of Windmill](https://app.windmill.dev/openapi.html) itself, to run jobs imperatively, using run_script and run_flow (their sync or async counterparts). This is a powerful way to define workflows, but it can be complex and verbose.
 
-It also requires to define the different jobs in different scripts. This is why, Windmill supports defining workflows as code in a single script in both [Python](../../getting_started/0_scripts_quickstart/2_python_quickstart/index.mdx) and [TypeScript](../../getting_started/0_scripts_quickstart/1_typescript_quickstart/index.mdx) using intuitive and lightweight syntax.
+It also requires to define the different jobs in different scripts. This is why Windmill supports defining workflows as code in a single script in both [Python](../../getting_started/0_scripts_quickstart/2_python_quickstart/index.mdx) and [TypeScript](../../getting_started/0_scripts_quickstart/1_typescript_quickstart/index.mdx) using intuitive and lightweight syntax.
 
 The syntax is highlighted in the below examples, note that the subtask are indeed executed as distinct jobs, with their own logs, and their relationship with their parent task is recorded which allows for the timeline of each task to be displayed in the UI.
 
