Merge remote-tracking branch 'remotes/origin/8.17' into 8.18

Author: flobernd

.github/workflows/docfx.yml

@@ -0,0 +1,74 @@
+name: 'CD'
+
+on:
+  workflow_call:
+    inputs:
+      target_branch:
+        description: 'The target branch to which the documentation should be pushed to.'
+        type: 'string'
+        required: true
+      name:
+        description: 'The name to use for the documentation folder (defaults to the name of the current ref)'
+        type: 'string'
+        required: false
+        default: ${{ github.ref_name }}
+
+concurrency:
+  group: 'docfx'
+  cancel-in-progress: false
+
+env:
+  # Configuration
+  GLOBAL_JSON_FILE: 'global.json'
+  CACHE_PATTERNS: '["**/*.[cf]sproj*", "**/*.Build.props"]'
+  # .NET SDK related environment variables
+  DOTNET_NOLOGO: 1
+  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
+  DOTNET_CLI_TELEMETRY_OPTOUT: 1
+  DOTNET_GENERATE_ASPNET_CERTIFICATE: 0
+
+jobs:
+  docfx:
+    name: 'DocFx'
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@v4'
+
+      - name: '.NET Setup'
+        uses: 'actions/setup-dotnet@v4'
+        with:
+          global-json-file: '${{ github.workspace }}/${{ env.GLOBAL_JSON_FILE }}'
+
+      - name: 'DocFX Setup'
+        run: |-
+          dotnet tool update -g docfx
+
+      # TODO: Remove 'stack'
+      - name: '.NET Cache Packages'
+        uses: 'actions/cache@v4'
+        with:
+          path: '~/.nuget/packages'
+          key: '${{ runner.os }}-nuget-stack-${{ hashFiles(fromJson(env.CACHE_PATTERNS)) }}'
+          restore-keys: '${{ runner.os }}-nuget-stack-'
+
+      - name: 'DocFx Build'
+        working-directory: 'docfx'
+        run: |-
+          docfx docfx.json
+          mv ./_site ./../..
+
+      - name: 'Checkout'
+        uses: 'actions/checkout@v4'
+        with:
+          ref: ${{ inputs.target_branch }}
+
+      - name: 'Commit'
+        run: |-
+          rm -r "./${{ inputs.name }}" || true
+          mv ../_site "./${{ inputs.name }}"
+          git config --global user.name '${{ github.actor }}'
+          git config --global user.email '${{ github.actor }}@users.noreply.github.com'
+          git add -A
+          git commit -am "Add ${{ inputs.name }}"
+          git push

.github/workflows/docfx_manual.yml

@@ -0,0 +1,12 @@
+name: 'DocFx'
+
+on:
+  workflow_dispatch:
+
+jobs:
+  docfx:
+    name: 'DocFx'
+    uses: ./.github/workflows/docfx.yml
+    with:
+      target_branch: 'refdoc'
+    secrets: 'inherit'

.github/workflows/release_stack.yml

@@ -16,3 +16,12 @@ jobs:
       release_tag: ${{ github.event.release.tag_name }}
       release_body: ${{ github.event.release.body }}
     secrets: 'inherit'
+
+  docfx:
+    name: 'DocFx'
+    if: ${{ !startsWith(github.event.release.tag_name, 'serverless-') }}
+    uses: ./.github/workflows/docfx.yml
+    with:
+      name: ${{ github.event.release.tag_name }}
+      target_branch: 'refdoc'
+    secrets: 'inherit'

Elasticsearch.sln

@@ -15,8 +15,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{362B2776
 		tests\Directory.Build.props = tests\Directory.Build.props
 	EndProjectSection
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Tests", "tests\Tests\Tests.csproj", "{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}"
-EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Tests.Core", "tests\Tests.Core\Tests.Core.csproj", "{70225C3F-393A-40F5-A778-8FF71A38C4C0}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Tests.Configuration", "tests\Tests.Configuration\Tests.Configuration.csproj", "{587DE66B-6FAB-4722-9C53-2812BEFB6A44}"
@@ -59,7 +57,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Tests.ClusterLauncher", "te
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Elastic.Clients.Elasticsearch.JsonNetSerializer", "src\Elastic.Clients.Elasticsearch.JsonNetSerializer\Elastic.Clients.Elasticsearch.JsonNetSerializer.csproj", "{8C9275D9-29CE-4A20-8FD5-6B26C6CAAADB}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Elastic.Clients.Elasticsearch.Serverless", "src\Elastic.Clients.Elasticsearch.Serverless\Elastic.Clients.Elasticsearch.Serverless.csproj", "{49D7F5A7-AA32-492B-B957-0E3325861F55}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Tests", "tests\Tests\Tests.csproj", "{6FD804B2-CE80-41CB-A411-2023F34C18FE}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -71,18 +69,6 @@ Global
 		{8F2EA767-8746-4816-B6EE-342BCB8F1AAB}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{8F2EA767-8746-4816-B6EE-342BCB8F1AAB}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{8F2EA767-8746-4816-B6EE-342BCB8F1AAB}.Release|Any CPU.Build.0 = Release|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Debug|x64.ActiveCfg = Debug|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Debug|x64.Build.0 = Debug|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Debug|x86.ActiveCfg = Debug|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Debug|x86.Build.0 = Debug|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Release|Any CPU.Build.0 = Release|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Release|x64.ActiveCfg = Release|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Release|x64.Build.0 = Release|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Release|x86.ActiveCfg = Release|Any CPU
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E}.Release|x86.Build.0 = Release|Any CPU
 		{70225C3F-393A-40F5-A778-8FF71A38C4C0}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{70225C3F-393A-40F5-A778-8FF71A38C4C0}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{70225C3F-393A-40F5-A778-8FF71A38C4C0}.Release|Any CPU.ActiveCfg = Release|Any CPU
@@ -119,17 +105,16 @@ Global
 		{8C9275D9-29CE-4A20-8FD5-6B26C6CAAADB}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{8C9275D9-29CE-4A20-8FD5-6B26C6CAAADB}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{8C9275D9-29CE-4A20-8FD5-6B26C6CAAADB}.Release|Any CPU.Build.0 = Release|Any CPU
-		{49D7F5A7-AA32-492B-B957-0E3325861F55}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{49D7F5A7-AA32-492B-B957-0E3325861F55}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{49D7F5A7-AA32-492B-B957-0E3325861F55}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{49D7F5A7-AA32-492B-B957-0E3325861F55}.Release|Any CPU.Build.0 = Release|Any CPU
+		{6FD804B2-CE80-41CB-A411-2023F34C18FE}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{6FD804B2-CE80-41CB-A411-2023F34C18FE}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{6FD804B2-CE80-41CB-A411-2023F34C18FE}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{6FD804B2-CE80-41CB-A411-2023F34C18FE}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{8F2EA767-8746-4816-B6EE-342BCB8F1AAB} = {D455EC79-E1E0-4509-B297-0DA3AED8DFF7}
-		{BDF1ABC2-8C52-4864-B824-B1FA27630E8E} = {362B2776-4B29-46AB-B237-56776B5372B6}
 		{70225C3F-393A-40F5-A778-8FF71A38C4C0} = {362B2776-4B29-46AB-B237-56776B5372B6}
 		{587DE66B-6FAB-4722-9C53-2812BEFB6A44} = {362B2776-4B29-46AB-B237-56776B5372B6}
 		{0B4DCA79-10CC-4CB8-95D3-A4EB8C98BE1C} = {362B2776-4B29-46AB-B237-56776B5372B6}
@@ -139,7 +124,7 @@ Global
 		{68D1BFDC-F447-4D2C-AF81-537807636610} = {1FE49D14-216A-41EE-A177-E42BFF53E0DC}
 		{F6162603-D134-4121-8106-2BA4DAD7350B} = {362B2776-4B29-46AB-B237-56776B5372B6}
 		{8C9275D9-29CE-4A20-8FD5-6B26C6CAAADB} = {D455EC79-E1E0-4509-B297-0DA3AED8DFF7}
-		{49D7F5A7-AA32-492B-B957-0E3325861F55} = {D455EC79-E1E0-4509-B297-0DA3AED8DFF7}
+		{6FD804B2-CE80-41CB-A411-2023F34C18FE} = {362B2776-4B29-46AB-B237-56776B5372B6}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {CE74F821-B001-4C69-A58D-CF81F8B0B632}

Packages.Serverless.slnf

@@ -58,6 +58,8 @@ Please refer to
 [the full documentation on elastic.co](https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/index.html)
 for comprehensive information on installation, configuration and usage.
 
+The API reference documentation is available [here](https://elastic.github.io/elasticsearch-net).
+
 ## Versions
 
 ### Elasticsearch 8.x Clusters

README.md

@@ -0,0 +1,2 @@
+_site
+api

docfx/.gitignore

@@ -3,9 +3,9 @@
     {
       "src": [
         {
-          "src": "./src/Elastic.Clients.Elasticsearch",
+          "src": "../src",
           "files": [
-            "**/*.csproj"
+            "**/Elastic.Clients.Elasticsearch.csproj"
           ]
         }
       ],
@@ -38,6 +38,7 @@
     "globalMetadata": {
       "_appName": "Elasticsearch.NET",
       "_appTitle": "Elasticsearch.NET",
+      "_appLogoPath": "images/logo.svg",
       "_enableSearch": true,
       "_disableContribution": true,
       "pdf": false

docfx.json renamed to docfx/docfx.json

@@ -0,0 +1,9 @@
+---
+_layout: landing
+---
+
+# Elasticsearch .NET API
+
+This is the home of the Elasticsearch .NET Client API Reference Documentation.
+
+Please click on `API` in the top menu to get to the API overview.

docfx/images/logo.svg

@@ -0,0 +1,2 @@
+- name: API
+  href: api/

docfx/index.md

@@ -26,22 +26,21 @@ Refer to the <<installation>> page to learn more.
 [discrete]
 === Connecting
 
-You can connect to the Elastic Cloud using an API key and the Elasticsearch 
-endpoint. 
+You can connect to the Elastic Cloud using an API key and your Elasticsearch 
+Cloud ID. 
 
 [source,net]
 ----
 var client = new ElasticsearchClient("<CLOUD_ID>", new ApiKey("<API_KEY>")); 
 ----
 
-Your Elasticsearch endpoint can be found on the **My deployment** page of your 
-deployment:
+You can find your Elasticsearch Cloud ID on the deployment page: 
 
-image::images/es-endpoint.jpg[alt="Finding Elasticsearch endpoint",align="center"]
+image::images/es-cloudid.jpg[alt="Cloud ID on the deployment page",align="center"]
 
-You can generate an API key on the **Management** page under Security.
-
-image::images/create-api-key.png[alt="Create API key",align="center"]
+To generate an API key, use the
+https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html[Elasticsearch Create API key API]
+or https://www.elastic.co/guide/en/kibana/current/api-keys.html#create-api-key[Kibana Stack Management].
 
 For other connection options, refer to the <<connecting>> section.
 
@@ -158,4 +157,4 @@ var response = await client.Indices.DeleteAsync("my_index");
 == Further reading
 
 * Refer to the <<recommendations>> page to learn more about how to use the 
-client the most efficiently. 
+client the most efficiently. 

docfx/toc.yml

@@ -292,13 +292,43 @@ As a last resort, the low-level client `Elastic.Transport` can be used to create
 
 [source,csharp]
 ----
+public class MyRequestParameters : RequestParameters
+{
+    public bool Pretty
+    {
+        get => Q<bool>("pretty");
+        init => Q("pretty", value);
+    }
+}
+
+// ...
+
 var body = """
-	{
-	  "name": "my-api-key",
-	  "expiration": "1d",   
-	  "...": "..."
-	}
-	""";
-
-var response = await client.Transport.RequestAsync<StringResponse>(HttpMethod.POST, "/_security/api_key", PostData.String(body));
+           {
+             "name": "my-api-key",
+             "expiration": "1d",   
+             "...": "..."
+           }
+           """;
+
+MyRequestParameters requestParameters = new()
+{
+    Pretty = true
+};
+
+var pathAndQuery = requestParameters.CreatePathWithQueryStrings("/_security/api_key",
+    client.ElasticsearchClientSettings);
+var endpointPath = new EndpointPath(Elastic.Transport.HttpMethod.POST, pathAndQuery);
+
+// Or, if the path does not contain query parameters: 
+// new EndpointPath(Elastic.Transport.HttpMethod.POST, "my_path")
+
+var response = await client.Transport
+    .RequestAsync<StringResponse>(
+        endpointPath,
+        PostData.String(body),
+        null,
+        null,
+        cancellationToken: default)
+    .ConfigureAwait(false);
 ----

docs/getting-started.asciidoc

@@ -6,6 +6,8 @@ The sections below provide tutorials on the most frequently used and some less o
 
 For a full reference, see the {ref}/[Elasticsearch documentation] and in particular the {ref}/rest-apis.html[REST APIs] section. The {net-client} follows closely the JSON structures described there.
 
+A .NET API reference documentation for the Elasticsearch client package is available https://elastic.github.io/elasticsearch-net[here].
+
 If you're new to {es}, make sure also to read {ref}/getting-started.html[Elasticsearch's quick start] that provides a good introduction.
 
 * <<recommendations, Usage recommendations>>
@@ -14,9 +16,10 @@ If you're new to {es}, make sure also to read {ref}/getting-started.html[Elastic
 
 NOTE: This is still a work in progress, more sections will be added in the near future.
 
-include::recommendations.asciidoc[]
+include::aggregations.asciidoc[]
+include::esql.asciidoc[]
 include::examples.asciidoc[]
-include::query.asciidoc[]
 include::mappings.asciidoc[]
-include::aggregations.asciidoc[]
-include::esql.asciidoc[]
+include::query.asciidoc[]
+include::recommendations.asciidoc[]
+include::transport.asciidoc[]