[8.1] Sync docs with main

.gitignore

@@ -30,7 +30,7 @@ test-results/*
 *.sbr
 *.DotSettings.user
 obj/
-[Rr]elease*/
+[Rr]elease/
 _ReSharper*/
 _NCrunch*/
 [Tt]est[Rr]esult*

docs/client-concepts/connection-pooling/exceptions/unrecoverable-exceptions.asciidoc

@@ -33,7 +33,7 @@ but by exiting the pipeline.
 
 By default, the client won't throw on any `TransportException` but instead return an invalid response
 that can be detected by checking the `.IsValid` property on the response. You can change this behaviour with
-by using `ThrowExceptions()` on <<configuration-options, `ConnectionSettings`>>.
+by using `ThrowExceptions()` on <<configuration, `ConnectionSettings`>>.
 
 [source,csharp]
 ----

docs/client-concepts/high-level/getting-started.asciidoc

@@ -41,7 +41,7 @@ var client = new ElasticClient(settings);
 ----
 
 In this example, a default index was also specified to use if no other index is supplied for the request or can be inferred for the
-POCO generic type parameter in the request. There are many other <<configuration-options,Configuration options>> on `ConnectionSettings`.
+POCO generic type parameter in the request. There are many other <<configuration,configuration options>> on `ConnectionSettings`.
 
 TIP: Specifying a default index is _optional_ but NEST may throw an exception if no index can be inferred for a given request. To understand more around how
 an index can be specified for a request, see <<index-name-inference,Index name inference>>.

docs/configuration.asciidoc

@@ -0,0 +1,247 @@
+[[configuration]]
+== Configuration
+
+Connecting to {es} with the client is easy, but it's possible that you'd like to 
+change the default connection behaviour. There are a number of configuration 
+options available on `ElasticsearchClientSettings` that can be used to control how the 
+client interact with {es}.
+
+=== Options on ElasticsearchClientSettings
+
+The following is a list of available connection configuration options on 
+`ElasticsearchClientSettings`:
+
+`Authentication`::
+
+An implementation of `IAuthenticationHeader` describing what http header to use 
+to authenticate with the product.
++
+ `BasicAuthentication` for basic authentication
++
+ `ApiKey` for simple secret token
++
+ `Base64ApiKey` for Elastic Cloud style encoded api keys
+
+`ClientCertificate`::
+
+Use the following certificates to authenticate all HTTP requests. You can also 
+set them on individual request using `ClientCertificates`.
+
+`ClientCertificates`::
+
+Use the following certificates to authenticate all HTTP requests. You can also 
+set them on individual request using `ClientCertificates`.
+
+`ConnectionLimit`::
+
+Limits the number of concurrent connections that can be opened to an endpoint. 
+Defaults to 80 (see `DefaultConnectionLimit`).
++
+For Desktop CLR, this setting applies to the `DefaultConnectionLimit` property 
+on the `ServicePointManager` object when creating `ServicePoint` objects, 
+affecting the default `IConnection` implementation.
++
+For Core CLR, this setting applies to the `MaxConnectionsPerServer` property on 
+the `HttpClientHandler` instances used by the `HttpClient` inside the default 
+`IConnection` implementation.
+
+`DeadTimeout`::
+
+The time to put dead nodes out of rotation (this will be multiplied by the 
+number of times they've been dead).
+
+`DefaultDisableIdInference`::
+
+Disables automatic Id inference for given CLR types.
++
+The client by default will use the value of a property named `Id` on a CLR type 
+as the `_id` to send to {es}. Adding a type will disable this behaviour for that 
+CLR type. If `Id` inference should be disabled for all CLR types, use 
+`DefaultDisableIdInference`.
+
+`DefaultFieldNameInferrer`::
+
+Specifies how field names are inferred from CLR property names.
++
+By default, the client camel cases property names. For example, CLR property 
+`EmailAddress` will be inferred as "emailAddress" {es} document field name.
+
+`DefaultIndex`::
+
+The default index to use for a request when no index has been explicitly 
+specified and no default indices are specified for the given CLR type specified 
+for the request.
+
+`DefaultMappingFor`::
+
+Specify how the mapping is inferred for a given CLR type. The mapping can infer 
+the index, id and relation name for a given CLR type, as well as control 
+serialization behaviour for CLR properties.
+
+`DisableAutomaticProxyDetection`::
+
+Disabled proxy detection on the webrequest, in some cases this may speed up the 
+first connection your appdomain makes, in other cases it will actually increase 
+the time for the first connection. No silver bullet! Use with care!
+
+`DisableDirectStreaming`::
+
+When set to true will disable (de)serializing directly to the request and 
+response stream and return a byte[] copy of the raw request and response. 
+Defaults to false.
+
+`DisablePing`::
+
+This signals that we do not want to send initial pings to unknown/previously 
+dead nodes and just send the call straightaway.
+
+`DnsRefreshTimeout`::
+
+DnsRefreshTimeout for the connections. Defaults to 5 minutes.
+
+`EnableDebugMode`::
+
+Turns on settings that aid in debugging like `DisableDirectStreaming()` and 
+`PrettyJson()` so that the original request and response JSON can be inspected. 
+It also always asks the server for the full stack trace on errors.
+
+`EnableHttpCompression`::
+
+Enable gzip compressed requests and responses.
+
+`EnableHttpPipelining`::
+
+Whether HTTP pipelining is enabled. The default is `true`.
+
+`EnableTcpKeepAlive`::
+
+Sets the keep-alive option on a TCP connection.
++
+For Desktop CLR, sets `ServicePointManager`.`SetTcpKeepAlive`.
+
+`EnableTcpStats`::
+
+Enable statistics about TCP connections to be collected when making a request.
+
+`GlobalHeaders`::
+
+Try to send these headers for every request.
+
+`GlobalQueryStringParameters`::
+
+Append these query string parameters automatically to every request.
+
+`MaxDeadTimeout`::
+
+The maximum amount of time a node is allowed to marked dead.
+
+`MaximumRetries`::
+
+When a retryable exception occurs or status code is returned this controls the 
+maximum amount of times we should retry the call to {es}.
+
+`MaxRetryTimeout`::
+
+Limits the total runtime including retries separately from `RequestTimeout`. 
+When not specified defaults to `RequestTimeout` which itself defaults to 60 
+seconds.
+
+`MemoryStreamFactory`::
+
+Provides a memory stream factory.
+
+`NodePredicate`::
+
+Register a predicate to select which nodes that you want to execute API calls 
+on. Note that sniffing requests omit this predicate and always execute on all 
+nodes. When using an `IConnectionPool` implementation that supports reseeding of 
+nodes, this will default to omitting master only node from regular API calls. 
+When using static or single node connection pooling it is assumed the list of 
+node you instantiate the client with should be taken verbatim.
+
+`OnRequestCompleted`::
+
+Allows you to register a callback every time a an API call is returned.
+
+`OnRequestDataCreated`::
+
+An action to run when the `RequestData` for a request has been created.
+
+`PingTimeout`::
+
+The timeout in milliseconds to use for ping requests, which are issued to 
+determine whether a node is alive.
+
+`PrettyJson`::
+
+Provide hints to serializer and products to produce pretty, non minified json.
++
+Note: this is not a guarantee you will always get prettified json.
+
+`Proxy`::
+
+If your connection has to go through proxy, use this method to specify the 
+proxy url.
+
+`RequestTimeout`::
+
+The timeout in milliseconds for each request to {es}.
+
+`ServerCertificateValidationCallback`::
+
+Register a `ServerCertificateValidationCallback` per request.
+
+`SkipDeserializationForStatusCodes`::
+
+Configure the client to skip deserialization of certain status codes, for 
+example, you run {es} behind a proxy that returns an unexpected json format.
+
+`SniffLifeSpan`::
+
+Force a new sniff for the cluster when the cluster state information is older 
+than the specified timespan.
+
+`SniffOnConnectionFault`::
+
+Force a new sniff for the cluster state every time a connection dies.
+
+`SniffOnStartup`::
+
+Sniff the cluster state immediately on startup.
+
+`ThrowExceptions`::
+
+Instead of following a c/go like error checking on response. `IsValid` do throw 
+an exception (except when `SuccessOrKnownError` is false) on the client when a 
+call resulted in an exception on either the client or the {es} server.
++
+Reasons for such exceptions could be search parser errors, index missing 
+exceptions, and so on.
+
+`TransferEncodingChunked`::
+
+Whether the request should be sent with chunked Transfer-Encoding.
+
+`UserAgent`::
+
+The user agent string to send with requests. Useful for debugging purposes to 
+understand client and framework versions that initiate requests to {es}.
+
+
+==== ElasticsearchClientSettings with ElasticsearchClient
+
+Here's an example to demonstrate setting configuration options using the client.
+
+[source,csharp]
+----
+var settings= new ElasticsearchClientSettings()
+    .DefaultMappingFor<Project>(i => i
+        .IndexName("my-projects")
+        .IdProperty(p => p.Name)
+    )
+    .EnableDebugMode()
+    .PrettyJson()
+    .RequestTimeout(TimeSpan.FromMinutes(2));
+
+var client = new ElasticsearchClient(settings);
+----

docs/high-level.asciidoc

@@ -52,8 +52,6 @@ include::{output-dir}/getting-started.asciidoc[]
 NEST uses sensible defaults for connecting to and interacting with an Elasticsearch cluster but provides numerous
 configuration options and components to change this behaviour
 
-* <<configuration-options, Configuration options>>
-
 * <<connection-pooling, Connection pools>>
 
 * <<modifying-default-connection, Modifying the default connection>>
@@ -62,8 +60,6 @@ configuration options and components to change this behaviour
 
 * <<function-as-a-service-environments, Using the Client in a Function-as-a-Service Environment>>
 
-include::client-concepts/connection/configuration-options.asciidoc[]
-
 include::client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc[]
 
 include::client-concepts/connection/modifying-default-connection.asciidoc[]

docs/index.asciidoc

@@ -3,13 +3,8 @@
 [[elasticsearch-net-reference]]
 = Elasticsearch .NET Client
 
-////
-IMPORTANT NOTE
-==============
-This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/index.asciidoc. 
-If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
-please modify the original csharp file found at the link and submit the PR with that change. Thanks!
-////
+:net-client: Elasticsearch .NET Client
+
 
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
@@ -19,6 +14,8 @@ include::install.asciidoc[]
 
 include::connecting.asciidoc[]
 
+include::configuration.asciidoc[]
+
 include::breaking-changes.asciidoc[]
 
 include::conventions.asciidoc[]
@@ -32,3 +29,7 @@ include::search.asciidoc[]
 include::query-dsl.asciidoc[]
 
 include::aggregations.asciidoc[]
+
+include::redirects.asciidoc[]
+
+include::release-notes/release-notes.asciidoc[]

docs/install.asciidoc

@@ -19,7 +19,7 @@ For SDK style projects, you can install the {es} client by running the following
 
 [source,text]
 ----
-dotnet add package Elastic.Clients.Elasticsearch -prerelease
+dotnet add package Elastic.Clients.Elasticsearch --prerelease
 ----
 
 This command adds a package reference to your project (csproj) file for the 

docs/redirects.asciidoc

@@ -0,0 +1,9 @@
+["appendix",role="exclude",id="redirects"]
+= Deleted pages
+
+The following pages have moved or been deleted.
+
+[role="exclude",id="configuration-options"]
+== Configuration options
+
+This page has moved. See <<configuration>>.

docs/release-notes/breaking-change-policy.asciidoc

@@ -0,0 +1,30 @@
+[[breaking-changes-policy]]
+== Breaking changes policy
+
+The {net-client} source code is generated from a https://github.com/elastic/elasticsearch-specification[formal specification of the Elasticsearch API]. This API specification is large, and although it is tested against hundreds of Elasticsearch test files, it may have discrepancies with the actual API that result in issues in the {net-client}.
+
+Fixing these discrepancies in the API specification results in code changes in the {net-client}, and some of these changes can require code updates in your applications.
+
+This section explains how these breaking changes are considered for inclusion in {net-client} releases.
+
+[discrete]
+==== Breaking changes in patch releases
+
+Some issues in the API specification are properties that have an incorrect type, such as a `long` that should be a `string`, or a required property that is actually optional. These issues can cause the {net-client} to not work properly or even throw exceptions.
+
+When a specification issue is discovered and resolved, it may require code updates in applications using the {net-client}. Such breaking changes are considered acceptable, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), as they introduce stability to APIs that may otherwise be unusable.
+
+[discrete]
+==== Breaking changes in minor releases
+
+Along with these bug fixes, the API specification is constantly refined, more precise type definitions are introduced to improve developer comfort and remove ambiguities. The specification of often-used APIs is fairly mature, so these changes happen generally on less often used APIs. These changes can also cause breaking changes requiring code updates which are considered _acceptable in minor releases_ (e.g. 8.0 -> 8.1).
+
+[discrete]
+==== Breaking changes in major releases
+
+Major releases (e.g. 7.x -> 8.x) can include larger refactorings of the API specification and the framework underlying the {net-client}. These refactorings are considered carefully and done only when they unlock new important features or new developments.
+
+[discrete]
+==== Elasticsearch API stability guarantees
+
+All Elasticsearch APIs have stability indicators, which imply potential changes. If an API is `stable` only additional non-breaking changes are added. In case of `experimental` APIs, breaking changes can be introduced any time, which means that these changes, will also be reflected in the {net-client}.

docs/release-notes/release-notes-8.0.0.asciidoc

@@ -2,7 +2,4 @@
 [[release-notes-8.0.0]]
 == Release-Notes 8.0.0
 
-include::release-notes-8.0.0-human.asciidoc[]
-include::release-notes-8.0.0-generated.asciidoc[]
-
-
+Coming soon!