[Docs] Add painless context details for bucket_script (#35142)

Fleshes out the details of the bucket_script context, adds an example
and corresponding doc test

docs/build.gradle

@@ -1128,3 +1128,33 @@ buildRestTests.setups['remote_cluster_and_leader_index'] = buildRestTests.setups
             index.number_of_shards: 1
             index.soft_deletes.enabled: true
 '''
+
+buildRestTests.setups['seats'] = '''
+  - do:
+        indices.create:
+          index: seats
+          body:
+            settings:
+              number_of_shards: 1
+              number_of_replicas: 0
+            mappings:
+              _doc:
+                properties:
+                  theatre:
+                    type: keyword
+                  cost:
+                    type: long
+  - do:
+        bulk:
+          index: seats
+          type: _doc
+          refresh: true
+          body: |
+            {"index":{}}
+            {"theatre": "Skyline", "cost": 1}
+            {"index":{}}
+            {"theatre": "Graye", "cost": 5}
+            {"index":{}}
+            {"theatre": "Graye", "cost": 8}
+            {"index":{}}
+            {"theatre": "Skyline", "cost": 10}'''

docs/painless/painless-contexts.asciidoc

@@ -44,7 +44,7 @@ specialized code may define new ways to use a Painless script.
                                     | {ref}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
 | Metric aggregation reduce         | <<painless-metric-agg-reduce-context, Painless Documentation>>
                                     | {ref}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
-| Bucket aggregation                | <<painless-bucket-agg-context, Painless Documentation>>
+| Bucket script aggregation         | <<painless-bucket-script-agg-context, Painless Documentation>>
                                     | {ref}/search-aggregations-pipeline-bucket-script-aggregation.html[Elasticsearch Documentation]
 | Watcher condition                 | <<painless-watcher-condition-context, Painless Documentation>>
                                     | {xpack-ref}/condition-script.html[Elasticsearch Documentation]

docs/painless/painless-contexts/index.asciidoc

@@ -28,7 +28,7 @@ include::painless-metric-agg-combine-context.asciidoc[]
 
 include::painless-metric-agg-reduce-context.asciidoc[]
 
-include::painless-bucket-agg-context.asciidoc[]
+include::painless-bucket-script-agg-context.asciidoc[]
 
 include::painless-analysis-predicate-context.asciidoc[]
 

docs/painless/painless-contexts/painless-bucket-agg-context.asciidoc

@@ -1,21 +0,0 @@
-[[painless-bucket-agg-context]]
-=== Bucket aggregation context
-
-Use a Painless script in an
-{ref}/search-aggregations-pipeline-bucket-script-aggregation.html[bucket aggregation]
-to calculate a value as a result in a bucket.
-
-*Variables*
-
-`params` (`Map`, read-only)::
-        User-defined parameters passed in as part of the query. The parameters
-        include values defined as part of the `buckets_path`.
-
-*Return*
-
-numeric::
-        The calculated value as the result.
-
-*API*
-
-The standard <<painless-api-reference, Painless API>> is available.

docs/painless/painless-contexts/painless-bucket-script-agg-context.asciidoc

@@ -0,0 +1,86 @@
+[[painless-bucket-script-agg-context]]
+=== Bucket script aggregation context
+
+Use a Painless script in an
+{ref}/search-aggregations-pipeline-bucket-script-aggregation.html[`bucket_script` pipeline aggregation]
+to calculate a value as a result in a bucket.
+
+==== Variables
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query. The parameters
+        include values defined as part of the `buckets_path`.
+
+==== Return
+
+numeric::
+        The calculated value as the result.
+
+==== API
+
+The standard <<painless-api-reference, Painless API>> is available.
+
+==== Example
+
+To run this example, first follow the steps in <<painless-context-examples, context examples>>.
+
+The painless context in a `bucket_script` aggregation provides a `params` map.  This map contains both
+user-specified custom values, as well as the values from other aggregations specified in the `buckets_path`
+property.
+
+This example takes the values from a min and max aggregation, calculates the difference,
+and adds the user-specified base_cost to the result:
+
+[source,Painless]
+--------------------------------------------------
+(params.max - params.min) + params.base_cost
+--------------------------------------------------
+
+Note that the values are extracted from the `params` map.  In context, the aggregation looks like this:
+
+[source,js]
+--------------------------------------------------
+GET /seats/_search
+{
+  "size": 0,
+  "aggs": {
+    "theatres": {
+      "terms": {
+        "field": "theatre",
+        "size": 10
+      },
+      "aggs": {
+        "min_cost": {
+          "min": {
+            "field": "cost"
+          }
+        },
+        "max_cost": {
+          "max": {
+            "field": "cost"
+          }
+        },
+        "spread_plus_base": {
+          "bucket_script": {
+            "buckets_path": { <1>
+              "min": "min_cost",
+              "max": "max_cost"
+            },
+            "script": {
+              "params": {
+                "base_cost": 5 <2>
+              },
+              "source": "(params.max - params.min) + params.base_cost"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:seats]
+<1> The `buckets_path` points to two aggregations (`min_cost`, `max_cost`) and adds `min`/`max` variables
+to the `params` map
+<2> The user-specified `base_cost` is also added to the script's `params` map