Update docs

Author: russcam

docs/aggregations/bucket/parent/parent-aggregation-usage.asciidoc

@@ -47,6 +47,7 @@ new ParentAggregation("name_of_parent_agg", typeof(CommitActivity)) <1>
 }
 ----
 <1> `join` field is determined from the _child_ type. In this example, it is `CommitActivity`
+
 <2> sub-aggregations are on the type determined from the `join` field. In this example, a `Project` is a parent of `CommitActivity`
 
 [source,javascript]

docs/aggregations/writing-aggregations.asciidoc

@@ -232,6 +232,7 @@ return s => s
         );
 ----
 <1> a list of aggregation functions to apply
+
 <2> Using LINQ's `Aggregate()` function to accumulate/apply all of the aggregation functions
 
 [[handling-aggregate-response]]
@@ -275,5 +276,6 @@ var maxPerChild = childAggregation.Max("max_per_child");
 maxPerChild.Should().NotBeNull(); <2>
 ----
 <1> Do something with the average per child. Here we just assert it's not null
+
 <2> Do something with the max per child. Here we just assert it's not null
 

docs/client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc

@@ -97,6 +97,7 @@ var pool = new CloudConnectionPool(cloudId, credentials); <2>
 var client = new ElasticClient(new ConnectionSettings(pool));
 ----
 <1> a username and password that can access Elasticsearch service on Elastic Cloud
+
 <2> `cloudId` is a value that can be retrieved from the Elastic Cloud web console
 
 This type of pool, like its parent the `SingleNodeConnectionPool`, is hardwired to opt out of

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

@@ -58,8 +58,11 @@ audit = await audit.TraceUnexpectedException(
 );
 ----
 <1> set up a cluster with 10 nodes
+
 <2> where node 2 on port 9201 always throws an exception
+
 <3> The first call to 9200 returns a healthy response
+
 <4> ...but the second call, to 9201, returns a bad response
 
 Sometimes, an unexpected exception happens further down in the pipeline. In this scenario, we
@@ -98,7 +101,9 @@ audit = await audit.TraceUnexpectedException(
 );
 ----
 <1> calls on 9200 set up to throw a `HttpRequestException` or a `WebException`
+
 <2> calls on 9201 set up to throw an `Exception`
+
 <3> Assert that the audit trail for the client call includes the bad response from 9200 and 9201
 
 An unexpected hard exception on ping and sniff is something we *do* try to recover from and failover to retrying on the next node.
@@ -143,6 +148,8 @@ audit = await audit.TraceUnexpectedException(
 );
 ----
 <1> `InnerException` is the exception that brought the request down
+
 <2> The hard exception that happened on ping is still available though
+
 <3> An exception can be hard to relate back to a point in time, so the exception is also available on the audit trail
 

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

@@ -81,6 +81,7 @@ var audit = new Auditor(() => VirtualClusterWith
 );
 ----
 <1> Always succeed on ping
+
 <2> ...but always fail on calls with a 401 Bad Authentication response
 
 Now, let's make a client call. We'll see that the first audit event is a successful ping
@@ -101,7 +102,9 @@ audit = await audit.TraceElasticsearchException(
 );
 ----
 <1> First call results in a successful ping
+
 <2> Second call results in a bad response
+
 <3> The reason for the bad response is Bad Authentication
 
 When a bad authentication response occurs, the client attempts to deserialize the response body returned;
@@ -135,6 +138,7 @@ audit = await audit.TraceElasticsearchException(
 );
 ----
 <1> Always return a 401 bad response with a HTML response on client calls
+
 <2> Assert that the response body bytes are null
 
 Now in this example, by turning on `DisableDirectStreaming()` on `ConnectionSettings`, we see the same behaviour exhibited
@@ -169,5 +173,6 @@ audit = await audit.TraceElasticsearchException(
 );
 ----
 <1> Response bytes are set on the response
+
 <2> Assert that the response contains `"nginx/"`
 

docs/client-concepts/connection-pooling/max-retries/respects-max-retry.asciidoc

@@ -84,6 +84,7 @@ audit = await audit.TraceCall(
 );
 ----
 <1> Set the maximum number of retries to 3
+
 <2> The client call trace returns an `MaxRetriesReached` audit after the initial attempt and the number of retries allowed
 
 In our previous example we simulated very fast failures, but in the real world, a call might take upwards of a second.

docs/client-concepts/connection-pooling/pinging/first-usage.asciidoc

@@ -92,9 +92,13 @@ await audit.TraceCalls(
 );
 ----
 <1> The first call goes to 9200, which succeeds
+
 <2> The 2nd call does a ping on 9201 because its used for the first time. This fails
+
 <3> So we ping 9202. This _also_ fails
+
 <4> We then ping 9203 because we haven't used it before and it succeeds
+
 <5> Finally, we assert that the connection pool has two nodes that are marked as dead
 
 All nodes are pinged on first use, provided they are healthy
@@ -121,5 +125,6 @@ await audit.TraceCalls(
 );
 ----
 <1> Pings on nodes always succeed
+
 <2> A successful ping on each node
 

docs/client-concepts/connection-pooling/request-overrides/disable-sniff-ping-per-request.asciidoc

@@ -65,8 +65,11 @@ audit = await audit.TraceCalls(
 );
 ----
 <1> disable sniffing
+
 <2> first call is a successful ping
+
 <3> sniff on startup call happens here, on the second call
+
 <4> No sniff on startup again
 
 Now, let's disable pinging on the request 
@@ -90,6 +93,7 @@ audit = await audit.TraceCall(
 );
 ----
 <1> disable ping
+
 <2> No ping after sniffing
 
 Finally, let's demonstrate disabling both sniff and ping on the request 
@@ -111,5 +115,6 @@ audit = await audit.TraceCall(
 );
 ----
 <1> disable ping and sniff
+
 <2> no ping or sniff before the call
 

docs/client-concepts/connection-pooling/round-robin/skip-dead-nodes.asciidoc

@@ -140,7 +140,9 @@ await audit.TraceCalls(
 );
 ----
 <1> The first call goes to 9200 which succeeds
+
 <2> The 2nd call does a ping on 9201 because its used for the first time. It fails so we wrap over to node 9202
+
 <3> The next call goes to 9203 which fails so we should wrap over
 
 A cluster with 2 nodes where the second node fails on ping 
@@ -191,5 +193,6 @@ await audit.TraceCalls(
 );
 ----
 <1> All the calls fail
+
 <2> After all our registered nodes are marked dead we want to sample a single dead node each time to quickly see if the cluster is back up. We do not want to retry all 4 nodes
 

docs/client-concepts/connection-pooling/sniffing/on-connection-failure.asciidoc

@@ -79,9 +79,13 @@ audit = await audit.TraceCalls(
 );
 ----
 <1> When the call fails on 9201, the following sniff succeeds and returns a new cluster state of healthy nodes. This cluster only has 3 nodes and the known masters are 9200 and 9202. A search on 9201 is setup to still fail once
+
 <2> After this second failure on 9201, another sniff will happen which returns a cluster state that no longer fails but looks completely different; It's now three nodes on ports 9210 - 9212, with 9210 and 9212 being master eligible.
+
 <3> We assert we do a sniff on our first known master node 9202 after the failed call on 9201
+
 <4> Our pool should now have three nodes
+
 <5> We assert we do a sniff on the first master node in our updated cluster
 
 ==== Sniffing after ping failure
@@ -147,8 +151,11 @@ audit = await audit.TraceCalls(
 );
 ----
 <1> We assert we do a sniff on our first known master node 9202
+
 <2> Our pool should now have three nodes
+
 <3> We assert we do a sniff on the first master node in our updated cluster
+
 <4> 9210 was already pinged after the sniff returned the new nodes
 
 ==== Client uses publish address

docs/client-concepts/connection-pooling/sniffing/on-startup.asciidoc

@@ -120,6 +120,7 @@ await audit.TraceCall(new ClientCall {
 });
 ----
 <1> Sniffing returns 8 nodes, starting from 9204
+
 <2> After successfully sniffing, the ping now happens on 9204
 
 ==== Prefers master eligible nodes

docs/client-concepts/connection-pooling/sniffing/role-detection.asciidoc

@@ -138,6 +138,7 @@ var audit = new Auditor(() => VirtualClusterWith
 };
 ----
 <1> Before the sniff, assert we only see three master only nodes
+
 <2> After the sniff, assert we now know about the existence of 20 nodes.
 
 After the sniff has happened on 9200 before the first API call, assert that the subsequent API
@@ -218,7 +219,9 @@ var audit = new Auditor(() => VirtualClusterWith
 };
 ----
 <1> for testing simplicity, disable pings
+
 <2> We only want to execute API calls to nodes in rack_one
+
 <3> After sniffing on startup, assert that the pool of nodes that the client will execute API calls against only contains the three nodes that are in `rack_one`
 
 With the cluster set up, assert that the sniff happens on 9200 before the first API call
@@ -295,6 +298,8 @@ await audit.TraceUnexpectedElasticsearchException(new ClientCall
 });
 ----
 <1> The audit trail indicates a sniff for the very first time on startup
+
 <2> The sniff succeeds because the node predicate is ignored when sniffing
+
 <3> when trying to do an actual API call however, the predicate prevents any nodes from being attempted
 

docs/client-concepts/high-level/analysis/writing-analyzers.asciidoc

@@ -100,6 +100,7 @@ var createIndexResponse = _client.Indices.Create("my-index", c => c
 );
 ----
 <1> Pre-defined list of English stopwords within Elasticsearch
+
 <2> Use the `standard_english` analyzer configured
 
 [source,javascript]
@@ -261,6 +262,7 @@ var createIndexResponse = _client.Indices.Create("questions", c => c
 );
 ----
 <1> Use an analyzer at index time that strips HTML tags
+
 <2> Use an analyzer at search time that does not strip HTML tags
 
 With this in place, the text of a question body will be analyzed with the `index_question` analyzer

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

@@ -107,6 +107,7 @@ var indexResponse = client.IndexDocument(person); <1>
 var asyncIndexResponse = await client.IndexDocumentAsync(person); <2>
 ----
 <1> synchronous method that returns an `IndexResponse`
+
 <2> asynchronous method that returns a `Task<IndexResponse>` that can be awaited
 
 NOTE: All methods available within NEST are exposed as both synchronous and asynchronous versions,

docs/client-concepts/high-level/indexing/indexing-documents.asciidoc

@@ -40,6 +40,7 @@ if (!indexResponse.IsValid)
 var indexResponseAsync = await client.IndexDocumentAsync(person); <2>
 ----
 <1> synchronous method that returns an IIndexResponse
+
 <2> asynchronous method that returns a Task<IIndexResponse> that can be awaited
 
 ==== Single documents with parameters
@@ -61,6 +62,7 @@ client.Index(person, i => i.Index("people")); <1>
 client.Index(new IndexRequest<Person>(person, "people")); <2>
 ----
 <1> fluent syntax
+
 <2> object initializer syntax
 
 ==== Multiple documents with `IndexMany`
@@ -111,8 +113,11 @@ if (indexManyResponse.Errors) <2>
 var indexManyAsyncResponse = await client.IndexManyAsync(people); <4>
 ----
 <1> synchronous method that returns an IBulkResponse
+
 <2> the response can be inspected to see if any of the bulk operations resulted in an error
+
 <3> If there are errors, they can be enumerated and inspected
+
 <4> asynchronous method that returns a Task<IBulkResponse> that can be awaited
 
 ==== Multiple documents with bulk
@@ -136,6 +141,7 @@ var asyncBulkIndexResponse = await client.BulkAsync(b => b
     .IndexMany(people)); <2>
 ----
 <1> synchronous method that returns an IBulkResponse, the same as IndexMany and can be inspected in the same way for errors
+
 <2> asynchronous method that returns a Task<IBulkResponse> that can be awaited
 
 ==== Multiple documents with `BulkAllObservable` helper
@@ -167,8 +173,11 @@ var bulkAllObservable = client.BulkAll(people, b => b
 });
 ----
 <1> how long to wait between retries
+
 <2> how many retries are attempted if a failure occurs
+
 <3> items per bulk request
+
 <4> perform the indexing and wait up to 15 minutes, whilst the BulkAll calls are asynchronous this is a blocking operation
 
 ==== Advanced bulk indexing
@@ -204,7 +213,10 @@ client.BulkAll(people, b => b
       }));
 ----
 <1> customise the individual operations in the bulk request before it is dispatched
+
 <2> Index each document into either even-index or odd-index
+
 <3> decide if a document should be retried in the event of a failure
+
 <4> if a document cannot be indexed this delegate is called
 

docs/client-concepts/high-level/indexing/ingest-nodes.asciidoc

@@ -57,5 +57,6 @@ var settings = new ConnectionSettings(pool).NodePredicate(n => n.IngestEnabled);
 var indexingClient = new ElasticClient(settings);
 ----
 <1> list of cluster nodes
+
 <2> predicate to select only nodes with ingest capabilities
 

docs/client-concepts/high-level/indexing/pipelines.asciidoc

@@ -92,12 +92,19 @@ var person = new Person
 var indexResponse = client.Index(person, p => p.Index("people").Pipeline("person-pipeline")); <8>
 ----
 <1> automatically create the mapping from the type
+
 <2> create an additional field to store the initials
+
 <3> map field as IP Address type
+
 <4> map GeoIp as object
+
 <5> uppercase the lastname
+
 <6> use a painless script to populate the new field
+
 <7> use ingest-geoip plugin to enrich the GeoIp object from the supplied IP Address
+
 <8> index the document using the created pipeline
 
 ==== Increasing timeouts
@@ -122,5 +129,6 @@ client.Bulk(b => b
 );
 ----
 <1> increases the server-side bulk timeout
+
 <2> increases the HTTP request timeout
 

docs/client-concepts/high-level/inference/field-inference.asciidoc

@@ -513,10 +513,15 @@ private class Precedence
 }
 ----
 <1> Even though this property has various attributes applied we provide an override on ConnectionSettings later that takes precedence.
+
 <2> Has a `TextAttribute`, `PropertyNameAttribute` and a `JsonPropertyAttribute` - the `TextAttribute` takes precedence.
+
 <3> Has both a `PropertyNameAttribute` and a `JsonPropertyAttribute` - the `PropertyNameAttribute` takes precedence.
+
 <4> `JsonPropertyAttribute` takes precedence.
+
 <5> This property we are going to hard code in our custom serializer to resolve to ask.
+
 <6> We are going to register a DefaultFieldNameInferrer on ConnectionSettings that will uppercase all properties.
 
 We'll create a custom `IPropertyMappingProvider` that renames any property named `AskSerializer` to `ask`.
@@ -562,7 +567,9 @@ usingSettings.Expect("data").ForField(Field<Precedence>(p => p.DataMember));
 usingSettings.Expect("DEFAULTFIELDNAMEINFERRER").ForField(Field<Precedence>(p => p.DefaultFieldNameInferrer));
 ----
 <1> Rename on the mapping for the `Precedence` type
+
 <2> Default inference for a field, if no other rules apply or are specified for a given field
+
 <3> Hook up the custom `IPropertyMappingProvider`
 
 The same naming rules also apply when indexing a document 

docs/client-concepts/high-level/inference/index-name-inference.asciidoc

@@ -85,6 +85,7 @@ var client = new ElasticClient(settings);
 var projectSearchResponse = client.Search<Project>();
 ----
 <1> a default index to use, when no other index can be inferred
+
 <2> a index to use when `Project` is the target POCO type
 
 will send a search request to the API endpoint