prepare to rewrite concepts

docs/README.md

@@ -20,4 +20,5 @@
 - [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)
+- [Technical Documentation](technical-documentation/README.md)
 - [FAQ](faq/README.md)

docs/concepts/README.md

@@ -2,11 +2,20 @@
 
 # Concepts
 
-- [Tasks](task/README.md)
-- [Task Group](task-group.md)
-- [Task Inputs](task-input/README.md)
-- [Task Env](task-env.md)
-- [Task EnvFile](task-env-file.md)
-- [Template](template.md)
+- [Runner, Task, and Group](runner-task-and-group.md)
+- [Inputs](inputs.md)
+- [Environments](environments.md)
+- [Template Rendering](template-rendering.md)
+- [Specialized Tasks](specialized-tasks.md)
+  - [DockerComposeTask](specialized-tasks/docker-compose-task.md)
+  - [ResourceMaker](specialized-tasks/resource-maker.md)
+  - [Notifier](specialized-tasks/notifider.md)
+  - [RemoteCmdTask](specialized-tasks/remote-cmd-task.md)
+  - [RsyncTask](specialized-tasks/rsync-task.md)
+  - [RecurringTask](specialized-tasks/recurring-task.md)
+  - [Checker](specialized-tasks/checker.md)
+  - [FlowTask](specialized-tasks/flow-task.md)
+- [Extending Task](extending-task.md)
+- [Extending CmdTask](extending-cmd-task.md)
 
-🔖 [Table of Contents](../README.md)
+🔖 [Table of Contents](../README.md)

docs/concepts/environments.md

@@ -0,0 +1,5 @@
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)
+
+# Environments
+
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)

docs/concepts/extending-cmd-task.md

@@ -0,0 +1,5 @@
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)
+
+# Extending CmdTask
+
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)

docs/concepts/extending-task.md

@@ -0,0 +1,5 @@
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)
+
+# Extending Task
+
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)

docs/concepts/inputs.md

@@ -0,0 +1,5 @@
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)
+
+# Inputs
+
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)

docs/concepts/runner-task-and-group.md

@@ -0,0 +1,5 @@
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)
+
+# Runner, Task, and Group
+
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)

docs/concepts/specialized-tasks/README.md

@@ -0,0 +1,14 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md)
+
+# Specialized Tasks
+
+- [DockerComposeTask](docker-compose-task.md)
+- [ResourceMaker](resource-maker.md)
+- [Notifier](notifider.md)
+- [RemoteCmdTask](remote-cmd-task.md)
+- [RsyncTask](rsync-task.md)
+- [RecurringTask](recurring-task.md)
+- [Checker](checker.md)
+- [FlowTask](flow-task.md)
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md)

docs/concepts/specialized-tasks/checker.md

@@ -0,0 +1,5 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+
+# Checker
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)

docs/concepts/specialized-tasks/docker-compose-task.md

@@ -0,0 +1,5 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+
+# DockerComposeTask
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)

docs/concepts/specialized-tasks/flow-task.md

@@ -0,0 +1,5 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+
+# FlowTask
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)

docs/concepts/specialized-tasks/notifier.md

@@ -0,0 +1,5 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+
+# Notifier
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)

docs/concepts/specialized-tasks/recurring-task.md

@@ -0,0 +1,5 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+
+# RecurringTask
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)

docs/concepts/specialized-tasks/remote-cmd-task.md

@@ -0,0 +1,6 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+
+# RemoteCmdTask
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+

docs/concepts/specialized-tasks/resource-maker.md

@@ -0,0 +1,6 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+
+# ResourceMaker
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+

docs/concepts/specialized-tasks/rsync-task.md

@@ -0,0 +1,6 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+
+# RSyncTask
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Specialized Tasks](README.md)
+

docs/technical-documentation/README.md

@@ -0,0 +1,37 @@
+🔖 [Table of Contents](../README.md)
+
+# Technical Documentation
+
+- [Tasks](tasks/README.md)
+  - [AnyTask](tasks/any-task.md)
+  - [BaseTask](tasks/base-task.md)
+  - [Task](tasks/task.md)
+  - [`@python_task` Decorator](tasks/python-task.md)
+  - [CmdTask](tasks/cmd-task.md)
+  - [DockerComposeTask](tasks/docker-compose-task.md)
+  - [ResourceMaker](tasks/resource-maker.md)
+  - [notifier](tasks/notifier.md)
+  - [FlowTask](tasks/flow-task.md)
+  - [BaseRemoteCmdTask](tasks/base-remote-cmd-task.md)
+  - [RemoteCmdTask](tasks/remote-cmd-task.md)
+  - [RsyncTask](tasks/rsync-task.md)
+  - [Checker](tasks/checker.md)
+  - [PathChecker](tasks/path-checker.md)
+  - [PortChecker](tasks/port-checker.md)
+  - [HTTPChecker](tasks/http-checker.md)
+  - [PathWatcher](tasks/path-watcher.md)
+  - [TimeWatcher](tasks/time-watcher.md)
+- [Task Group](task-group.md)
+- [Task Inputs](task-inputs/README.md)
+  - [Input](task-inputs/input.md)
+  - [BoolInput](task-inputs/bool-input.md)
+  - [ChoiceInput](task-inputs/choice-input.md)
+  - [FloatInput](task-inputs/float-input.md)
+  - [IntInput](task-inputs/int-input.md)
+  - [PasswordInput](task-inputs/password-input.md)
+  - [StrInput](task-inputs/str-input.md)
+- [Task Env](task-envs/README.md)
+  - [Env](task-envs/env.md)
+  - [EnvFile](task-envs/env-file.md)
+
+🔖 [Table of Contents](../README.md)

docs/technical-documentation/task-envs/README.md

@@ -0,0 +1,9 @@
+🔖 [Table of Contents](../../README.md) / [Technical Documentation](../README.md)
+
+# Task Envs
+
+- [Env](env.md)
+- [EnfFile](env-file.md)
+
+🔖 [Table of Contents](../../README.md) / [Technical Documentation](../README.md)
+

docs/technical-documentation/task-envs/env-file.md

@@ -0,0 +1,54 @@
+🔖 [Table of Contents](../../README.md) / [Technical Documentation](../README.md) / [Task Envs](README.md)
+
+# EnvFile
+
+# Technical Specification
+
+<!--start-doc-->
+## `EnvFile`
+
+Represents a handler for an environment file, facilitating the creation and management of environment variables
+(Env objects) based on the contents of the specified environment file.
+
+__Attributes:__
+
+- `path` (`str`): The path to the environment file.
+- `prefix` (`Optional[str]`): An optional prefix to be applied to environment variables.
+- `should_render` (`bool`): Flag to determine if the environment values should be rendered.
+
+__Examples:__
+
+```python
+from zrb import EnvFile, Task
+import os
+CURRENT_DIR = os.dirname(__file__)
+task = Task(
+    name='task',
+    env_files=[
+        EnvFile(path=os.path.join(CURRENT_DIR, '.env'), prefix='SYSTEM')
+    ]
+)
+```
+
+
+### `EnvFile.get_envs`
+
+Retrieves a list of Env objects based on the environment file. If a prefix is provided, it is
+applied to the environment variable names.
+
+__Returns:__
+
+`List[Env]`: A list of Env objects representing the environment variables defined in the file.
+
+__Examples:__
+
+```python
+from zrb import Env, EnvFile
+env_file = EnvFile(path='some_file.env')
+envs: List[Env] = env_file.get_envs()
+```
+
+
+<!--end-doc-->
+
+🔖 [Table of Contents](../../README.md) / [Technical Documentation](../README.md) / [Task Envs](README.md)

docs/technical-documentation/task-envs/env.md

@@ -0,0 +1,108 @@
+🔖 [Table of Contents](../../README.md) / [Technical Documentation](../README.md) / [Task Envs](README.md)
+
+# Env
+
+# Technical Specification
+
+<!--start-doc-->
+## `Env`
+
+Env Represents an environment configuration for a task, encapsulating details such as environment name, OS-specific
+environment name, default values, and rendering behavior.
+
+__Attributes:__
+
+- `name` (`str`): Environment name as recognized by the task.
+- `os_name` (`Optional[str]`): The corresponding name in the OS's environment, if different from 'name'. You can set os_name to empty string if you don't want the environment to be linked to OS environment name.
+- `default` (`JinjaTemplate`): Default value of the environment variable.
+- `should_render` (`bool`): Flag to determine if the environment value should be rendered.
+
+__Examples:__
+
+```python
+from zrb import Env, Task
+task = Task(
+    name='task',
+    envs=[
+        Env(name='DATABASE_URL', os_name='SYSTEM_DATABASE_URL', default='postgresql://...')
+    ]
+)
+```
+
+
+### `Env._Env__get_prefixed_name`
+
+Constructs the prefixed name of the environment variable.
+
+This method is intended for internal use only.
+
+__Arguments:__
+
+- `name` (`str`): The base name of the environment variable.
+- `prefix` (`str`): The prefix to be added to the name.
+
+__Returns:__
+
+`str`: The prefixed name of the environment variable.
+
+### `Env.get`
+
+Retrieves the value of the environment variable, considering an optional prefix.
+
+__Arguments:__
+
+- `prefix` (`str`): An optional prefix to distinguish different environments (e.g., 'DEV', 'PROD').
+
+__Returns:__
+
+`str`: The value of the environment variable, considering the prefix and default value.
+
+__Examples:__
+
+```python
+from zrb import Env
+import os
+os.environ['DEV_SERVER'] = 'localhost'
+os.environ['PROD_SERVER'] = 'example.com'
+env = Env(name='HOST', os_name='SERVER', default='0.0.0.0')
+print(env.get('DEV'))   # will show 'localhost'
+print(env.get('PROD'))  # will show 'example.com'
+print(env.get('STAG'))  # will show '0.0.0.0'
+```
+
+
+### `Env.get_default`
+
+Retrieves the default value of the environment variable.
+
+__Returns:__
+
+`str`: The default value of the environment variable.
+
+### `Env.get_name`
+
+Retrieves the name of the environment variable.
+
+__Returns:__
+
+`str`: The name of the environment variable.
+
+### `Env.get_os_name`
+
+Retrieves the OS-specific name of the environment variable.
+
+__Returns:__
+
+`Optional[str]`: The OS-specific name of the environment variable.
+
+### `Env.should_render`
+
+Determines whether the environment value should be rendered.
+
+__Returns:__
+
+`bool`: True if the environment value should be rendered, False otherwise.
+
+<!--end-doc-->
+
+🔖 [Table of Contents](../../README.md) / [Technical Documentation](../README.md) / [Task Envs](README.md)