diff --git a/README.md b/README.md index 149b3df9..0443b615 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ ![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/zrb/android-chrome-192x192.png) +[Documentation](https://github.com/state-alchemists/zrb/blob/main/docs/README.md) + # 🤖 Zrb: Your Automation Powerhouse -With Zrb, you can write your automation tasks like this: +Zrb allows you to write your automation tasks in Python and declaratively: ```python @@ -20,59 +22,13 @@ math.add_task(Task( )) ``` -You can then access the task in various ways. - -__Using CLI with arguments__ - -```bash -zrb math add 4 5 -``` - -Result: - -``` -9 -To run again: zrb math add --a=4 --b=5 -``` - -__Using CLI with keyword arguments__ - -```bash -zrb math add --a 4 --b 5 -``` - -Result: - -``` -9 -To run again: zrb math add --a=4 --b=5 -``` - -__Using CLI with incomplete arguments__ - -```bash -zrb math add 4 -``` - -Result: - -``` -b [0]: 5 -9 -To run again: zrb math add 4 -``` - -__Using Web Interface__ - -```bash -zrb server start -``` +Once defined, you will be able to access your automation tasks from the CLI, Web Interface, or via HTTP API. -Result (you need to access `http://localhost:21213`) +For more complex scenario, you can also defined Task dependencies (upstreams) and retry mechanisms. You can also make a scheduled tasks, just like in Apache Airflow. -![](https://raw.githubusercontent.com/state-alchemists/zrb/refs/heads/1.0.0/_images/web.png) +Furthermore, Zrb has some builtin tasks to manage monorepo, generate FastAPI application, or play around with LLM. -__More:__ +See the [getting started guide](https://github.com/state-alchemists/zrb/blob/main/docs/recipes/getting-started/README.md) for more information. Or just watch the demo: [![Video Title](https://img.youtube.com/vi/W7dgk96l__o/0.jpg)](https://www.youtube.com/watch?v=W7dgk96l__o) diff --git a/docs/recipes/README.md b/docs/recipes/README.md index 1453d02b..a859bc63 100644 --- a/docs/recipes/README.md +++ b/docs/recipes/README.md @@ -2,4 +2,7 @@ # Recipes +- [Getting Started](getting-started/README.md) +- [Others](others/README.md) + 🔖 [Table of Contents](../README.md) diff --git a/docs/recipes/getting-started/README.md b/docs/recipes/getting-started/README.md new file mode 100644 index 00000000..776758a9 --- /dev/null +++ b/docs/recipes/getting-started/README.md @@ -0,0 +1,8 @@ +🔖 [Table of Contents](../../README.md) / [Recipes](../README.md) + +# Recipes - Getting Started + +- [Defining A Task](defining-a-task.md) + +🔖 [Table of Contents](../../README.md) / [Recipes](../README.md) + diff --git a/_images/web.png b/docs/recipes/getting-started/_images/web.png similarity index 100% rename from _images/web.png rename to docs/recipes/getting-started/_images/web.png diff --git a/docs/recipes/getting-started/defining-a-task.md b/docs/recipes/getting-started/defining-a-task.md new file mode 100644 index 00000000..26e132f0 --- /dev/null +++ b/docs/recipes/getting-started/defining-a-task.md @@ -0,0 +1,105 @@ +🔖 [Table of Contents](../README.md) + +# Defining A Task + +This example demonstrates how to create a simple math tool using Zrb, a powerful automation framework. We'll create an "add" function within a "math" group. + +## Code Example + +Create a file named `zrb_init.py` with the following content: + +```python +from zrb import cli, Task, Group, IntInput + +# Create a 'math' group +math = cli.add_group(Group("math", description="Math tools")) + +# Add an 'add' task to the 'math' group +math.add_task(Task( + name="add", + input=[ + IntInput("a", description="First number"), + IntInput("b", description="Second number") + ], + action=lambda ctx: ctx.input.a + ctx.input.b +)) +``` + +This code does the following: +1. Imports necessary components from Zrb. +2. Creates a "math" group for organizing related tools. +3. Adds an "add" task to the "math" group, which takes two integer inputs and returns their sum. + +## Usage + +After defining the task, you can access it in various ways: + +### 1. Using CLI with Positional Arguments + +```bash +zrb math add 4 5 +``` + +Output: +``` +9 +To run again: zrb math add --a=4 --b=5 +``` + +### 2. Using CLI with Keyword Arguments + +```bash +zrb math add --a 4 --b 5 +``` + +Output: +``` +9 +To run again: zrb math add --a=4 --b=5 +``` + +### 3. Using CLI with Incomplete Arguments + +If you provide incomplete arguments, Zrb will prompt for the missing values: + +```bash +zrb math add 4 +``` + +Output: +``` +b [0]: 5 +9 +To run again: zrb math add 4 +``` + +### 4. Using Web Interface + +Zrb also provides a web interface for interacting with your tasks: + +```bash +zrb server start +``` + +This command starts a web server, allowing you to access and run your tasks through a browser interface. + +![](_images/web.png) + +## Key Features Demonstrated + +- **Group Creation**: Organizing related tasks into a group ("math"). +- **Task Definition**: Creating a task with a name, inputs, and an action. +- **Input Handling**: Using `IntInput` to specify and validate integer inputs. +- **Flexible CLI Usage**: Supporting both positional and keyword arguments. +- **Interactive Prompts**: Requesting missing arguments when needed. +- **Web Interface**: Providing a graphical interface for task execution. + +## Next Steps + +- Explore creating more complex tasks and groups. +- Investigate additional input types provided by Zrb. +- Learn about task dependencies and advanced Zrb features. + +For more information, refer to the Zrb documentation or run `zrb --help` for available commands and options. + +🔖 [Table of Contents](../README.md)