diff --git a/README.md b/README.md index 613ccc24..1a9bf275 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ To use Zrb, you need to be familiar with CLI. Zrb task definitions are written in [Python](https://www.python.org/), and we have a [very good reason](https://github.com/state-alchemists/zrb/blob/main/docs/faq/why-python.md) behind the decision. -## Zrb as a low-code framework +## Zrb is A Low-Code Framework Let's see how you can build and run a [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) application. @@ -60,7 +60,7 @@ zrb project deploy-fastapp --fastapp-deploy-mode "microservices" You can visit [our tutorials](https://github.com/state-alchemists/zrb/blob/main/docs/tutorials/README.md) to see more cool tricks. -## Zrb as a task-automation framework +## Zrb is A Task-Automation Tool Aside from the built-in capabilities, Zrb also allows you to define your automation commands in Python. To do so, you must create/modify a file named `zrb_init.py`. @@ -103,7 +103,7 @@ To learn more about this, you can visit [our getting started guide](https://gith # 🫰 Installation -## βš™οΈ In local machine +## βš™οΈ In Local Machine Installing Zrb in your system is as easy as typing the following command in your terminal: @@ -115,7 +115,7 @@ Like any other Python package, you can install Zrb in your [virtual environment] > ⚠️ If the command doesn't work, you probably don't have Pip/Python on your computer. See `Main prerequisites` subsection to install them. -## πŸ‹ With docker +## πŸ‹ With Docker If you prefer to work with Docker, you can create a file named `docker-compose.yml` @@ -154,7 +154,7 @@ You will be able to access Zrb by using docker exec: docker exec -it zrb zsh ``` -# βœ… Main prerequisites +# βœ… Main Prerequisites Since Zrb is written in Python, you need to install a few things before installing Zrb: @@ -179,7 +179,7 @@ ln -s venv/bin/python3 /usr/local/bin/python If you prefer Python distribution like [conda](https://docs.conda.io/en/latest/), that might work as well. -# βœ”οΈ Other prerequisites +# βœ”οΈ Other Prerequisites If you want to generate applications using Zrb and run them on your computer, you will also need: @@ -198,7 +198,7 @@ If you want to generate applications using Zrb and run them on your computer, yo - πŸ¦† `Pulumi` - You need Pulumi to deploy your applications -# 🏁 Getting started +# 🏁 Getting Started We have an excellent [getting started guide](https://github.com/state-alchemists/zrb/blob/main/docs/getting-started.md) to help you cover the basics. Make sure to check it outπŸ˜‰. @@ -212,7 +212,7 @@ Help Red Skull to click the donation button: [![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/donator.png)](https://stalchmst.com/donation) -# πŸŽ‰ Fun fact +# πŸŽ‰ Fun Fact > Madou Ring Zaruba (ι­”ε°ŽθΌͺアルバ, Madōrin Zaruba) is a Madougu which supports bearers of the Garo Armor. [(Garo Wiki | Fandom)](https://garo.fandom.com/wiki/Zaruba) diff --git a/docs/README.md b/docs/README.md index 1b6fc738..f0419073 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,7 +5,7 @@ - [Configurations](configurations.md) - [Tutorials](tutorials/README.md) - [Troubleshooting](troubleshooting/README.md) -- [Oops, I Did it Again: Most Common Mistakes When Working with Zrb](oops-i-did-it-again/README.md) +- [Oops, I Did it Again: The Most Common Mistakes When Working with Zrb](oops-i-did-it-again/README.md) - [Contributor Guide](contributor-guide.md) - [Maintainer Guide](maintainer-guide.md) - [FAQ](faq/README.md) diff --git a/docs/oops-i-did-it-again/README.md b/docs/oops-i-did-it-again/README.md index 3c935194..7c97f406 100644 --- a/docs/oops-i-did-it-again/README.md +++ b/docs/oops-i-did-it-again/README.md @@ -1,10 +1,15 @@ πŸ”– [Table of Contents](../README.md) / [Oops, I Did It Again](README.md) -# Oops, I Did It Again: Most Common Mistakes When Working with Zrb +# Oops, I Did It Again: The Most Common Mistakes When Working with Zrb Collection of the most common mistakes when working with Zrb -- [Defining Different Tasks With The Same Name](defining-different-tasks-with-the-same-name.md) +> πŸ’ƒ "I'm not that innocent" +- [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) + + πŸ”– [Table of Contents](../README.md) / [Oops, I Did It Again](README.md) \ No newline at end of file diff --git a/docs/oops-i-did-it-again/defining-different-tasks-with-the-same-name.md b/docs/oops-i-did-it-again/defining-different-tasks-with-the-same-name-under-the-same-group.md similarity index 59% rename from docs/oops-i-did-it-again/defining-different-tasks-with-the-same-name.md rename to docs/oops-i-did-it-again/defining-different-tasks-with-the-same-name-under-the-same-group.md index 5c11f159..6ccecb22 100644 --- a/docs/oops-i-did-it-again/defining-different-tasks-with-the-same-name.md +++ b/docs/oops-i-did-it-again/defining-different-tasks-with-the-same-name-under-the-same-group.md @@ -1,6 +1,6 @@ πŸ”– [Table of Contents](../README.md) / [Oops, I Did It Again](README.md) -# Defining Different Tasks With The Same Name +# Defining Different Tasks With The Same Name Under The Same Group ```python from zrb import CmdTask, runner @@ -18,7 +18,9 @@ hello2 = CmdTask( runner.register(hello2) ``` -You can see that `hello1` and `hello2` share the same name. Thus, `hello2` will override `hello1` +You can see that `hello1` and `hello2` share the same name. Both of them also has the same `group` (i.e., not defined). + +In this case, `hello2` will override `hello1`. This leads to tricky situation. For example, you believe that `zrb hello` should yield `hello mars`, yet it keep showing `hello world`. @@ -28,7 +30,16 @@ First of all, detecting the problem will be easier if you use the same conventio - Use single quote instead of double quote for string value whenever possible - Not using space between property name and property value (i.e., `name='hello'`) -Once you do so, you can use `search` feature in your IDE/text editor (e.g., `name='hello'`). Make sure every task name is unique. +Once you do so, you can use `search` feature in your IDE/text editor (e.g., `name='hello'`). Make sure every task name is unique so that they don't accidentally overwrite each other. + +# Avoiding the Problem + +To avoid the problem completely, you can do: + +- Always un `zrb` or `zrb [task-groups]` to see list of registered task name. +- Organize your tak definiton location. + - Put tasks that has similar context under the same `task-group`. + - Put those tasks physically close to each other (at the same file of under the same directory). πŸ”– [Table of Contents](../README.md) / [Oops, I Did It Again](README.md) diff --git a/docs/oops-i-did-it-again/not-registering-a-task-to-a-runner.md b/docs/oops-i-did-it-again/not-registering-a-task-to-a-runner.md new file mode 100644 index 00000000..f6fdf1b6 --- /dev/null +++ b/docs/oops-i-did-it-again/not-registering-a-task-to-a-runner.md @@ -0,0 +1,53 @@ +πŸ”– [Table of Contents](../README.md) / [Oops, I Did It Again](README.md) + +# Not Registering A Task to A Runner + +```python +from zrb import CmdTask, runner + +hello = CmdTask( + name='hello', + cmd='echo "hello world"' +) +``` + +```bash +zrb hello +# task not found +``` + +If you want your task to be available through the CLI, you need to register it to Zrb's runner. + +> __NOTE:__ A task that is not registered to Zrb's runner will not be available through the CLI, but can still be used as upstreams/checkers. + +# Avoiding the Problem + +Don't forget to register your task to Zrb's runner + +```python +from zrb import CmdTask, runner + +hello = CmdTask( + name='hello', + cmd='echo "hello world"' +) +runner.register(hello) +``` + +If you are using `@python_task` decorator, you can use `runner` property as follow: + +```python +from typing import Any +from zrb import python_task, runner + +@python_task( + name='hello', + runner=runner +) +def hello(*args: Any, **kwargs: Any): + task = kwargs.get('_task') + task.print_out('hello world') +``` + + +πŸ”– [Table of Contents](../README.md) / [Oops, I Did It Again](README.md) \ No newline at end of file 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 new file mode 100644 index 00000000..e69de29b