docs: add tutorial

* Restructure get-started section
* Add server example to executors

Author: AndreyMarkinPPC

docs/development/overview.md

@@ -1,7 +1,10 @@
 # Build on top of garf
 
-You can create on top of `garf` you can have a couple of options:
+While `garf` provides you with a lot of built-in functionality it might not be
+sufficient for an API of your choice.
 
-* [Create an API client](create-api-client.md) to be used with `ApiReportFetcher` class
-* [Create an API response parser](create-api-response-parser.md) to be customize how `ApiReportFetcher` parses response from API
+To make `garf` work with your API explore options below:
+
+* [Create an API client](create-api-client.md) to be used with `ApiReportFetcher` class.
+* [Create an API response parser](create-api-response-parser.md) to be customize how `ApiReportFetcher` parses response from API.
 * [Create a library](create-garf-library.md) and expose it as `garf` plugin.

docs/get-started/cli.md

@@ -1,38 +1,97 @@
 # Overview
 
-`garf` can be used in a multiple ways.
-
-<div class="grid cards" markdown>
-
--   :material-console-line: **Installation**
-
-    ----
-
-    Install `garf-executors` to run queries against APIs.
-
-    [:octicons-arrow-right-24: More information](installation.md)
-
--   :simple-python: **Library**
-
-    ----
-
-    Integrate `garf` into your libraries.
-
-    [:octicons-arrow-right-24: More information](library.md)
-
--   :material-console-line: **CLI**
-
-    ----
-
-    Execute queries in your terminal.
-
-    [:octicons-arrow-right-24: More information](cli.md)
-
--   :simple-fastapi: **Server**
-
-    ----
-
-    Run `garf` as FastAPI endpoint.
-
-    [:octicons-arrow-right-24: More information](server.md)
-</div>
+Let's use `garf` to query [https://restful-api.dev](https://restful-api.dev) (publicly available API) and save results to BigQuery.
+
+## Installation
+
+/// tab | pip
+```
+pip install garf-executors
+```
+///
+
+/// tab | uv
+```
+uv add garf-executors
+```
+///
+
+## Create query
+
+[https://restful-api.dev](https://restful-api.dev) has ` https://api.restful-api.dev/objects` endpoint to get list of objects in the following format:
+
+```json
+[
+   {
+      "id": "1",
+      "name": "Google Pixel 6 Pro",
+      "data": {
+         "color": "Cloudy White",
+         "capacity": "128 GB"
+      }
+   },
+   {
+      "id": "2",
+      "name": "Apple iPhone 12 Mini, 256GB, Blue",
+      "data": null
+   },
+   {
+      "id": "3",
+      "name": "Apple iPhone 12 Pro Max",
+      "data": {
+         "color": "Cloudy White",
+         "capacity GB": 512
+      }
+   }
+]
+```
+
+Support we want to get `id`, `name` and `color` of each device.
+
+Let's create a query to get this information.
+
+```sql
+SELECT
+  id AS device_id,
+  name AS device_name,
+  data.color AS device_color
+FROM objects
+```
+
+We can save this query to a local file called `devices.sql`.
+
+```bash
+echo "
+SELECT
+  id AS device_id,
+  name AS device_name,
+  data.color AS device_color
+FROM objects" > devices.sql
+```
+
+## Execute query
+
+Since the API we're working with is of REST type we can use `garf`'s built-in `rest` source and provide API address to get data from.
+
+We'll use `garf` CLI tool get the data. The only thing we need to specify is root endpoint where API is located (`https://api.restful-api.dev` in our case).
+
+```bash
+garf devices.sql --source rest \
+  --source.endpoint=https://api.restful-api.dev \
+  --output bq
+```
+
+!!! note
+    Since we want to write data to BigQuery we specified `bq` output type.
+    By default results will be stored in default project (`GOOGLE_CLOUD_PROJECT`) in `garf` dataset under name `devices`.
+
+## Next steps
+
+Congratulations, you executed your first query with `garf`!
+
+Now you can explore various options `garf` provides:
+
+* **How to write queries**: Learn an extensive [SQL syntax](../usage/queries.md) capabilities `garf` supports.
+* **How to use garf in your Python projects**: `garf` makes it easy to [fetch data](../usage/fetcher.md) and works with fetched [reports](../usage/reports.md).
+* **Supported writers**: Learn where you can [write data](../usage/writers.md) fetched from your APIs.
+* **Executors**: Learn how to process multiple queries with [executors](../usage/executors.md).

docs/get-started/index.md

@@ -31,6 +31,12 @@ pip install garf-executors[sql]
 ```
 ///
 
+/// tab | server
+```bash
+pip install garf-executors[server]
+```
+///
+
 ## Usage
 
 After `garf-executors` is installed you can use `garf` utility to perform fetching.
@@ -70,6 +76,31 @@ query_executor.execute(
 ```
 ///
 
+/// tab | server
+
+!!!note
+    Ensure that API endpoint for `garf` is running.
+    ```bash
+    python garf_executors.entrypoints.server
+    ```
+
+```bash
+curl -X 'POST' \
+  'http://127.0.0.1:8000/api/execute' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "source": "API_SOURCE",
+  "title": "query",
+  "query": "YOUR_QUERY_HERE",
+  "context": {
+    "writer": "OUTPUT_TYPE"
+  }
+}'
+```
+
+///
+
 ## Customization
 
 ### Source
@@ -117,6 +148,7 @@ query_executor.execute(
   context=context
 )
 ```
+///
 
 ### Macro
 

docs/get-started/installation.md

@@ -52,13 +52,7 @@ markdown_extensions:
 
 nav:
   - Home: index.md
-  - Get Started:
-    - get-started/index.md
-    - Installation: get-started/installation.md
-    - Quickstart:
-      - Library: get-started/library.md
-      - CLI: get-started/cli.md
-      - Server: get-started/server.md
+  - Tutorial: get-started/index.md
   - Usage:
     - Core:
       - usage/core.md