docs(custom-target): add an overview section for custom target (#882)

Author: georgeh0

docs/docs/custom_ops/custom_targets.mdx

@@ -8,12 +8,29 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 A custom target allows you to export data to any destination you want, such as databases, cloud storage, file systems, APIs, or other external systems.
+You can either continuously update the destination to keep it in sync with the latest exported data, or simply publish the changes as a changelog to somewhere.
+
+## Overview
 
 Custom targets are defined by two components:
 
 *   A **target spec** that configures the behavior and connection parameters for the target.
 *   A **target connector** that handles the actual data export operations.
 
+When you define a flow within CocoIndex, you define how data are transformed, collected and exported, without worrying about how to handle data change (insert, update, delete). CocoIndex handles it for you.
+However, a target connects CocoIndex flow and external systems, and needs to synchronize changes of data from the CocoIndex flow to outside.
+The implementation of a target connector needs to deal with changes, in two aspects:
+
+-   **Setup changes**.
+    They're for basic setup of a target's corresponding infrastructure (e.g. a table, a directory) without specific data.
+    When users add a new target, delete an existing target, or make changes to the target spec,
+    the framework will trigger the connector to apply these setup changes by calling `apply_setup_change()`.
+    The connector needs apply corresponding setup changes to the external system, e.g. create/delete a table, update/delete a directory, etc.
+
+-   **Data changes**.
+    They're changes of specific data exported to the target.
+    During the flow is running, when new rows-to-export appear, or existing ones are updated or deleted in the CocoIndex flow, the framework will trigger the connector to apply these data changes by calling `mutate()`, e.g. insert/update/delete a row in a table, write/delete a file, etc.
+
 ## Target Spec
 
 The target spec defines the configuration parameters for your custom target. When you use this target in a flow (typically by calling [`export()`](/docs/core/flow_def#export)), you instantiate this target spec with specific parameter values.
@@ -44,7 +61,7 @@ Notes:
 
 A target connector handles the actual data export operations for your custom target. It defines how data should be written to your target destination.
 
-Target connectors implement two categories of methods: **setup methods** for managing target infrastructure (similar to DDL operations in databases), and **data methods** for handling specific data operations (similar to DML operations).
+Target connectors implement two categories of methods: setup methods to deal with setup changes, and data methods to deal with data changes.
 
 <Tabs>
 <TabItem value="python" label="Python" default>
@@ -158,7 +175,21 @@ def prepare(spec: CustomTarget) -> PreparedCustomTarget:
 
 If not provided, the original spec will be passed directly to `mutate`.
 
-### Complete Example
+## Best Practices
+
+### Idempotency of Methods with Side Effects
+
+`apply_setup_change()` and `mutate()` are the two methods that are expected to produce side effects.
+We expect them to be idempotent, i.e. when calling them with the same arguments multiple times, the effect should remain the same.
+
+For example,
+- For `apply_setup_change()`, if the target is a directory, it should be a no-op if we try to create it (`previous` is `None`) when the directory already exists, and also a no-op if we try to delete it (`current` is `None`) when the directory does not exist.
+- For `mutate()`, if a mutation is a deletion, it should be a no-op if the row does not exist.
+
+This is to make sure when the system if left in an intermediate state, e.g. interrupted in the middle between a change is made and CocoIndex notes down the change is completed, the targets can still be gracefully rolled forward to the desired states after the system is resumed.
+
+
+## Example
 
 In this example, we define a custom target that accepts data with the following fields:
 - `filename` (key field)
@@ -247,21 +278,4 @@ For simplicity, the type hints can be omitted and a `dict` will be created inste
 </TabItem>
 </Tabs>
 
-## Best Practices
-
-### Idempotency of Methods with Side Effects
-
-`apply_setup_change()` and `mutate()` are the two methods that are expected to produce side effects.
-We expect them to be idempotent, i.e. when calling them with the same arguments multiple times, the effect should remain the same.
-
-For example,
-- For `apply_setup_change()`, if the target is a directory, it should be a no-op if we try to create it (`previous` is `None`) when the directory already exists, and also a no-op if we try to delete it (`current` is `None`) when the directory does not exist.
-- For `mutate()`, if a mutation is a deletion, it should be a no-op if the row does not exist.
-
-This is to make sure when the system if left in an intermediate state, e.g. interrupted in the middle between a change is made and CocoIndex notes down the change is completed, the targets can still be gracefully rolled forward to the desired states after the system is resumed.
-
-## Examples
-
-The cocoindex repository contains the following examples of custom targets:
-
-*   In the [custom_output_files](https://github.com/cocoindex-io/cocoindex/blob/main/examples/custom_output_files/main.py) example, `LocalFileTarget` exports data to local HTML files.
+See the [custom_output_files](https://github.com/cocoindex-io/cocoindex/blob/main/examples/custom_output_files/main.py) for the an end-to-end example.