update docs

state-alchemists · Nov 5, 2023 · 349a011 · 349a011
1 parent 3f5b87f
commit 349a011
Show file tree

Hide file tree

Showing 26 changed files with 273 additions and 37 deletions.
diff --git a/docs/concepts/tasks/README.md b/docs/concepts/tasks/README.md
@@ -3,14 +3,16 @@
 
 # Type of Tasks
 
-There are many task types in Zrb. Every task has their own specific use-cases:
+There are many task types in Zrb. Every task has its own specific use cases:
 
 
 - [CmdTask](cmd-task.md): Run a CLI command
 - [Task (python task)](python-task.md): Run a Python function
 - [DockerComposeTask](docker-compose-task.md): Run a Docker compose Command
-- [Resource Maker](resource-maker.md): Generate artifacts/resources based on templates
+- [ResourceMaker](resource-maker.md): Generate artifacts/resources based on templates
 - [FlowTask](flow-task.md): Put `CmdTask` and `python task` into single flow.
+- [RemoteCmdTask](remote-cmd-task.md)
+- [RsyncTask](remote-cmd-task.md)
 - [Checkers (HttpChecker, PortChecker, and PathChecker)](checkers.md): Check parent task's readiness.
 
 As every task are extended from `BaseTask`, you will see that most of them share some common parameters.
@@ -38,7 +40,7 @@ Aside from the documentation, you can always dive down into [the source code](ht
 
 > __Note:__ Never initiate `BaseTask` directly, use `Task` instead.
 
-# Task overview
+# Task Overview
 
 Tasks are building blocks of your automation.
 
@@ -143,11 +145,11 @@ Triggered         ┌─────────► Ready ◄──┐
 - `Retry`: The task has been failed and will be re-started.
 - `Ready`: The task is ready.
 
-# Common task parameters
+# Common Task Parameters
 
 Zrb tasks share some common parameters like `name`, `icon`, `color`, `description`, etc.
 
-Some parameters are required, while some others are optionals. Please refer to [each specific task documentation](#type-of-tasks) for more complete list of parameters.
+Some parameters are required, while some others are optional. Please refer to [each specific task documentation](#type-of-tasks) for a more complete list of parameters.
 
 ## `name`
 
@@ -390,7 +392,7 @@ Boolean, whether return upstreams result instead of current task result or not.
 ## `on_failed`
 
 
-# Common task methods
+# Common Task Methods
 
 Every task share some common methods like `run`, `check`, and `to_function`.
 

diff --git a/docs/concepts/tasks/cmd-task.md b/docs/concepts/tasks/cmd-task.md
@@ -69,7 +69,7 @@ You can then run the task by invoking:
 zrb say-hello --name=John
 ```
 
-# CmdTask parameters
+# CmdTask Parameters
 
 Every [task parameters](./task.md#common-task-parameters) are applicable here. Additionally, a `CmdTask` has it's own specific parameters.
 

diff --git a/docs/concepts/tasks/docker-compose-task.md b/docs/concepts/tasks/docker-compose-task.md
@@ -49,7 +49,7 @@ zrb run-container
 
 Under the hood, Zrb will read your `compose_file` populate it with some additional configuration, and create a runtime compose file `._<compose-file>-<task-name>.runtime.yml`. Zrb will use the run the runtime compose file to run your `compose_cmd` (i.e., `docker compose -f <compose-file>-<task-name>.runtime.yml <compose-cmd>`)
 
-# DockerComposeTask parameters
+# DockerComposeTask Parameters
 
 Every [task parameters](./task.md#common-task-parameters) are applicable here. Additionally, a `DockerComposeTask` has it's own specific parameters.
 
@@ -159,7 +159,7 @@ runner.register(start_container)
 ## `preexec_fn`
 
 
-# DockerComposeTask methods
+# DockerComposeTask Methods
 
 Please refer to [common task methods](./README.md#common-task-methods).
 

diff --git a/docs/concepts/tasks/python-task.md b/docs/concepts/tasks/python-task.md
@@ -75,7 +75,7 @@ zrb say-hello --name=John
 
 You can also use `async` function if you think you need to.
 
-# Task parameters
+# Task Parameters
 
 Every [common task parameters](./README.md#common-task-parameters) are applicable here. Additionally, a `Task` has some specific parameters.
 
@@ -155,7 +155,7 @@ Runner this task registered to.
 - __Possible values:__ `runner` or `None`
 - __Default value:__ `runner`
 
-# Task methods
+# Task Methods
 
 Please refer to [common task methods](./README.md#common-task-methods).
 

diff --git a/docs/concepts/tasks/remote-cmd-task.md b/docs/concepts/tasks/remote-cmd-task.md
@@ -0,0 +1,30 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Tasks](README.md)
+
+# RemoteCmdTask
+
+```python
+from zrb import (
+    runner, CmdTask, RemoteCmdTask, RemoteConfig, PasswordInput
+)
+
+install_curl = RemoteCmdTask(
+    name='install-curl',
+    inputs=[
+        PasswordInput(name='passsword')
+    ],
+    remote_configs=[
+        RemoteConfig(
+            host='192.168.1.10,
+            user='ubuntu,
+            password='{{input.password}}'
+        )
+    ],
+    cmd=[
+        'sudo apt update',
+        'sudo apt install curl --y'
+    ]
+)
+runner.register(install_curl)
+```
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Tasks](README.md)
diff --git a/docs/concepts/tasks/resource-maker.md b/docs/concepts/tasks/resource-maker.md
@@ -59,7 +59,7 @@ runner.register(add_mit_license)
 Note that your template folder might contains a very complex structure. For example, you can make your application boiler plate into a template.
 
 
-# ResourceMaker parameters
+# ResourceMaker Parameters
 
 Every [task parameters](./task.md#common-task-parameters) are applicable here. Additionally, a `ResourceMaker` has it's own specific parameters.
 

diff --git a/docs/concepts/tasks/rsync-task.md b/docs/concepts/tasks/rsync-task.md
@@ -0,0 +1,53 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Tasks](README.md)
+
+# RSyncTask
+
+```python
+from zrb import (
+    runner, CmdTask, RSyncTask, RemoteConfig, PasswordInput, StrInput
+)
+
+upload = RSyncTask(
+    name='upload',
+    inputs=[
+        PasswordInput(name='passsword'),
+        StrInput(name='src'),
+        StrInput(name='dst'),
+    ],
+    remote_configs=[
+        RemoteConfig(
+            host='192.168.1.10,
+            user='ubuntu,
+            password='{{input.password}}'
+        )
+    ],
+    is_remote_src=False,
+    is_remote_dst=True
+    src='{{input.src}}',
+    dst='{{input.dst}}',
+)
+runner.register(upload)
+
+download = RSyncTask(
+    name='download',
+    inputs=[
+        PasswordInput(name='passsword'),
+        StrInput(name='src'),
+        StrInput(name='dst'),
+    ],
+    remote_configs=[
+        RemoteConfig(
+            host='192.168.1.10,
+            user='ubuntu,
+            password='{{input.password}}'
+        )
+    ],
+    is_remote_src=True,
+    is_remote_dst=False
+    src='{{input.src}}',
+    dst='{{input.dst}}',
+)
+runner.register(download)
+```
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Tasks](README.md)
diff --git a/docs/faq/README.md b/docs/faq/README.md
@@ -3,5 +3,7 @@
 # FAQ
 
 - [Why Python](why-python.md)
+- [Does Zrb has A Scheduler](does-zrb-has-a-scheduler.md)
+- [How to get data from other tasks](how-to-get-data-from-other-tasks.md)
 
 🔖 [Table of Contents](../README.md)
diff --git a/docs/faq/do-zrb-has-a-scheduler.md b/docs/faq/do-zrb-has-a-scheduler.md
diff --git a/docs/faq/does-zrb-has-a-scheduler.md b/docs/faq/does-zrb-has-a-scheduler.md
@@ -0,0 +1,20 @@
+🔖 [Table of Contents](../README.md) / [FAQ](README.md)
+
+# Do Zrb has a Scheduler?
+
+No. Zrb focus is to help you run complicated tasks in a single run. You will need third party alternatives to make your tasks run by schedule.
+
+# Why No Scheduler?
+
+Implementing a Scheduler seems to be easy at the first glance.
+
+However, there are a few reasons why we don't build our own internal scheduler:
+
+- There are a lot of battle-proven tools and strategy you can already use.
+- Maintaining internal scheduler might distract us from the main goal.
+
+# What Can I Do to Make a Scheduled Task?
+
+Don't worry, there are some [tricks](../tutorials/run-task-by-schedule.md) you can use. For example you can use infinite loop, Cronjob, or even orchestrator like Airflow.
+
+🔖 [Table of Contents](../README.md) / [FAQ](README.md)
diff --git a/docs/faq/how-to-get-data-from-other-tasks.md b/docs/faq/how-to-get-data-from-other-tasks.md
@@ -0,0 +1,11 @@
+🔖 [Table of Contents](../README.md) / [FAQ](README.md)
+
+# How to Get Data from Other Tasks?
+
+Tasks are usually be isolated from each other.
+
+But it some cases, sharing data among tasks can be quite handy. Zrb doesn't support this mechanism out of the box, but you can make use `_ZRB_EXECUTION_ID` to achieve what you want.
+
+See [this tutorial](../tutorials/getting-data-from-other-tasks.md) for more information.
+
+🔖 [Table of Contents](../README.md) / [FAQ](README.md)
diff --git a/docs/faq/why-python.md b/docs/faq/why-python.md
@@ -4,9 +4,11 @@
 
 Python is a general multi-purpose language. It support a lot of pogramming paradigms like OOP/FP, or procedural. Writing a configuration in Python let you do a lot of things like control structure, etc.
 
-Python has been around since the 90's, and you won't have to worry about the language. Many people already familiar with the language. Even if you are new to the language, learning Python will be highly rewarding.
+Python has been around since the 90's, and it was battle tested everywhere. Many people already familiar with the language. Even if you are new to the language, learning Python will be highly rewarding.
 
-However, there are a lot of tools out there that don't use Python. So, why Python? Why not YAML/HCL/anything else?
+Nevertheless, there are a lot of tools out there that don't use Python.
+
+So, we can extend the question: Why Python? Why not YAML/HCL/anything else?
 
 # Why not YAML?
 
@@ -105,11 +107,30 @@ zrb install-curl
 
 If you are not familiar with Python, Ansible Playbook will makes more sense for you. Ansible task definition is carefully crafted to cover most use cases.
 
-The trickiest part when you work with Ansible or any YAML based configuration is you need to understand the specification. Docker compose for example, has a very different configuration from ansible eventough both of them are using YAML.
+The trickiest part when you work with Ansible or any YAML based configuration is you need to understand the tool specification. Docker compose for example, has a very different configuration from ansible eventough both of them are using YAML.
 
 On the other hand, Python is just Python. You can use list comprehension, loop, branch, or anything you already know. The syntax highlighting, hint, and auto completion are commonly provided in your favorite tools.
 
 Even if you are new to Python, Zrb Task Definition is not very difficult to grasp. You can follow the [getting started guide](../getting-started.md) and tag along.
 
 
+# Why not Anything Else?
+
+There are a few of considerations.
+
+- Python is interpreted.
+
+  Other language like go or rust might give you a better performance, but the iteration is generally slower. You need to compile them into machine code in order to make it works.
+
+  Zrb is an automation tool. It helps developers doing their job. It doesn't serve any service to the end user. Thus, we can sacrifice the execution speed a little bit. No one will complain if your deployment is late for 0.5 seconds.
+
+- Python is popular.
+
+  If you are using macOS, there is a high chance you already have Python installed in your computer. Even if you are using Linux/Windows, installing Python is usually quite easy.
+
+- We want to focus on the features.
+
+  Building our own parser can be fun and challenging, but it doesn't bring any value to the user. We want to build Zrb on top of something battle proven, something you are already familiar with, something you can hack on without learning the whole new concept and specs.
+
+
 🔖 [Table of Contents](../README.md) / [FAQ](README.md)
diff --git a/docs/oops-i-did-it-again/README.md b/docs/oops-i-did-it-again/README.md
@@ -2,19 +2,14 @@
 
 # Oops, I Did It Again: The Most Common Mistakes When Working with Zrb
 
-Collection of the most common mistakes when working with Zrb
+Collection of the most common mistakes when working with Zrb (You are not that innocent 😏)
+
+[![Oops I Did It Again](https://img.youtube.com/vi/CduA0TULnow/0.jpg)](https://www.youtube.com/watch?v=CduA0TULnow)
 
 
 - [Not Registering A Task to A Runner](not-registering-a-task-to-a-runner.md)
 - [Defining Different Tasks With The Same Name Under The Same Group](defining-different-tasks-with-the-same-name-under-the-same-group.md)
 - [Using The Same Variable to Define Different Task](using-the-same-variable-to-define-different-task.md)
 
-<div style="text-align: center;">
-
-[![Oops I Did It Again](https://img.youtube.com/vi/CduA0TULnow/0.jpg)](https://www.youtube.com/watch?v=CduA0TULnow)
-
-💃 I'm not that innocent
-
-</div>
 
 🔖 [Table of Contents](../README.md) / [Oops, I Did It Again](README.md)
diff --git a/docs/oops-i-did-it-again/using-the-same-variable-to-define-different-task.md b/docs/oops-i-did-it-again/using-the-same-variable-to-define-different-task.md
@@ -0,0 +1,11 @@
+🔖 [Table of Contents](../README.md) / [Oops, I Did It Again](README.md)
+
+# Using The Same Variable to Define Different Task
+
+```python
+from zrb import runner, CmdTask
+
+
+```
+
+🔖 [Table of Contents](../README.md) / [Oops, I Did It Again](README.md)
diff --git a/docs/quirks.md b/docs/quirks.md
@@ -17,5 +17,7 @@
         - The last one takes greater priority
     - `env` will override each other, the last one takes greater priority
     - If you define a `DockerComposeTask`, it will automatically fill your environment with the ones you use in your docker-compose file. The environment defined that way will have a very low priority. They will be overridden by both `env_files` and `env`.
+- You cannot have an input named: `_task`, `_args` or `_execution_id`
+- You cannot have an environment named `_execution_id`
 
 🔖 [Table of Contents](README.md)
diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
@@ -6,6 +6,7 @@
 - [Development to Deployment: Low Code](development-to-deployment-low-code.md)
 - [Run Task programmatically](run-task-programmatically.md)
 - [Run Task by Schedule](run-task-by-schedule.md)
+- [Getting Data from Other Tasks](getting-data-from-other-tasks.md)
 - [Define Task Dynamically](define-task-dynamically.md)
 - [Copy and Re-use task](copy-and-reuse-task.md)
 - [Extending CmdTask: Sending Message to Slack](extending-cmd-task.md)

diff --git a/docs/tutorials/define-task-dynamically.md b/docs/tutorials/define-task-dynamically.md
@@ -39,6 +39,11 @@ You can try to run the tasks:
 
 ```bash
 zrb show-fruits
+
+# or run the generated task individually:
+zrb show-apple
+zrb show-orange
+zrb show-grapes
 ```
 
 It should run all previous tasks as well.