Add documentation and example YAMLs for task and task_group configuration formats (#530)

This PR enhances documentation to clearly show both supported formats
(list & dictionary) for defining tasks and task groups in DAG Factory
configurations, helping users understand their options and migrate
toward the recommended list-based approach.

We already have tests covering both list and dictionary-based tasks &
taskgroups being added previously in #487 and #491, hence the PR solely
focuses on adding example YAMLs and reflecting those in docs.

Docs preview:
<img width="767" height="1141" alt="Screenshot 2025-08-01 at 1 43 57 AM"
src="https://github.com/user-attachments/assets/8e970dee-d056-46bd-b572-ca54fc9b3f27"
/>



closes: #529

Author: pankajkoti

dev/dags/example_dag_factory.yml

@@ -10,6 +10,10 @@ basic_example_dag:
   schedule_interval: "0 3 * * *"
   render_template_as_native_obj: True
   catchup: false
+  task_groups:
+    - group_name: "example_task_group"
+      tooltip: "this is an example task group"
+      dependencies: [task_1]
   tasks:
     - task_id: "task_1"
       operator: airflow.operators.bash.BashOperator
@@ -20,6 +24,7 @@ basic_example_dag:
       dependencies: [task_1]
     - task_id: "task_3"
       operator: airflow.operators.bash.BashOperator
-      bash_command: "echo 2"
+      bash_command: "echo 3"
       dependencies: [task_1]
+      task_group_name: "example_task_group"
 # ----8<---   [ end: example_dag_yaml_configuration ]

dev/dags/example_dag_factory_tasks_taskgroups_as_dict_format.yml

@@ -0,0 +1,30 @@
+default:
+  default_args:
+    start_date: 2024-11-11
+
+# ----8<---   [ start: example_dag_dict_configuration ]
+basic_example_dag_dict_format:
+  default_args:
+    owner: "custom_owner"
+  description: "this is an example dag using dictionary format for tasks and task_groups"
+  schedule_interval: "0 3 * * *"
+  render_template_as_native_obj: True
+  catchup: false
+  task_groups:
+    example_task_group:
+      tooltip: "this is an example task group"
+      dependencies: [task_1]
+  tasks:
+    task_1:
+      operator: airflow.operators.bash.BashOperator
+      bash_command: "echo 1"
+    task_2:
+      operator: airflow.operators.bash.BashOperator
+      bash_command: "echo 2"
+      dependencies: [task_1]
+    task_3:
+      operator: airflow.operators.bash.BashOperator
+      bash_command: "echo 3"
+      dependencies: [task_1]
+      task_group_name: example_task_group
+# ----8<---   [ end: example_dag_dict_configuration ]

docs/configuration/configuring_workflows.md

@@ -9,13 +9,36 @@ You can define multiple workflows within a single YAML file based on your requir
 - **default_args**: Common arguments for all tasks.
 - **schedule**/**schedule_interval**: Specifies the execution schedule.
 - **tasks**: Defines the [Airflow tasks](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html) in your workflow.
+- **task_groups**: Defines [Airflow task groups](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html#taskgroups) to organize and group related tasks.
 
-### Example DAG Configuration
+## Example DAG Configuration
+
+### Task and Task Group Configuration Formats
+
+DAG Factory supports two formats for defining `tasks` and `task_groups`:
+
+#### List Format (Recommended)
+
+The **list format** is the recommended and more readable approach. In this format, tasks are defined as a list where each task includes a `task_id` field, and task groups are also defined as a list where each group includes a `group_name` field:
+
+!!! info "Version Support"
+    List format support was introduced in version 1.0.0.
 
 ```title="example_dag_factory.yml"
 --8<-- "dev/dags/example_dag_factory.yml:example_dag_yaml_configuration"
 ```
 
+#### Dictionary Format (Legacy)
+
+The **dictionary format** is also supported for backward compatibility. In this format, tasks are defined as a dictionary where the key is the task ID, and task groups are also defined as a dictionary where the key is the group name:
+
+```title="example_dag_factory_tasks_taskgroups_as_dict_format.yml"
+--8<-- "dev/dags/example_dag_factory_tasks_taskgroups_as_dict_format.yml:example_dag_dict_configuration"
+```
+
+!!! note "Format Recommendation"
+    While both formats are supported, **we recommend using the list format** as it is more readable and easier to maintain.
+
 ### Check out more configuration params
 
 - [Environment variables](environment_variables.md)