From 5522a8a51377423c3ae108175fd9d9cb835cc25a Mon Sep 17 00:00:00 2001
From: Pankaj Koti <pankajkoti699@gmail.com>
Date: Tue, 17 Dec 2024 16:33:06 +0530
Subject: [PATCH] Add docs

---
 docs/configuration/callbacks.rst | 51 ++++++++++++++++++++++++++++++++
 docs/configuration/index.rst     |  1 +
 2 files changed, 52 insertions(+)
 create mode 100644 docs/configuration/callbacks.rst

diff --git a/docs/configuration/callbacks.rst b/docs/configuration/callbacks.rst
new file mode 100644
index 000000000..9ffbc246f
--- /dev/null
+++ b/docs/configuration/callbacks.rst
@@ -0,0 +1,51 @@
+.. _callbacks:
+
+Callbacks
+=========
+
+Cosmos supports callback functions that execute at the end of a task's execution when using ``ExecutionMode.LOCAL``.
+These callbacks can be used for various purposes, such as uploading files from the target directory to remote
+storage. While this feature has been available for some time, users may not be fully aware of its capabilities.
+
+With the Cosmos 1.8.0 release, several helper functions were added in the ``cosmos/io.py`` module. These functions
+provide examples of callback functions that can be hooked into Cosmos DAGs to upload files from the project’s
+target directory to remote cloud storage providers such as AWS S3, GCP GS, and Azure WASB.
+
+Example: Using Callbacks with a Single Operator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To demonstrate how to specify a callback function for uploading files from the target directory, here’s an example
+using a single operator in an Airflow DAG:
+
+.. literalinclude:: ../../dev/dags/example_operators.py
+    :language: python
+    :start-after: [START single_operator_callback]
+    :end-before: [END single_operator_callback]
+
+Example: Using Callbacks with ``remote_target_path`` (Airflow 2.8+)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're using Airflow 2.8 or later, you can leverage the :ref:`remote_target_path` configuration to upload files
+from the target directory to a remote storage. Below is an example of how to define a callback helper function in your
+``DbtDag`` that utilizes this configuration:
+
+.. literalinclude:: ../../dev/dags/cosmos_callback_dag.py
+    :language: python
+    :start-after: [START cosmos_callback_example]
+    :end-before: [END cosmos_callback_example]
+
+Custom Callbacks
+~~~~~~~~~~~~~~~~
+
+The helper functions introduced in Cosmos 1.8.0 are just examples of how callback functions can be written and passed
+to Cosmos DAGs. Users are not limited to using these predefined functions — they can also create their own custom
+callback functions to meet specific needs. These custom functions can be provided to Cosmos DAGs, where they will
+receive the path to the cloned project directory and the Airflow task context, which includes DAG and task instance
+metadata.
+
+Limitations and Contributions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Currently, callback support is available only when using ``ExecutionMode.LOCAL``. Contributions to extend this
+functionality to other execution modes are welcome and encouraged. You can reference the implementation for
+``ExecutionMode.LOCAL`` to add support for other modes.
diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst
index f6e60f61b..6c47884e9 100644
--- a/docs/configuration/index.rst
+++ b/docs/configuration/index.rst
@@ -27,3 +27,4 @@ Cosmos offers a number of configuration options to customize its behavior. For m
    Compiled SQL <compiled-sql>
    Logging <logging>
    Caching <caching>
+   Callbacks <callbacks>