Update documentation

Author: russcam

.paket/Paket.Restore.targets

@@ -53,10 +53,10 @@
     </PropertyGroup>
 
     <!-- If shasum and awk exist get the hashes -->
-    <Exec Condition=" '$(PaketRestoreCachedHasher)' != '' " Command="$(PaketRestoreCachedHasher)" ConsoleToMSBuild='true'>
+    <Exec StandardOutputImportance="Low" Condition=" '$(PaketRestoreCachedHasher)' != '' " Command="$(PaketRestoreCachedHasher)" ConsoleToMSBuild='true'>
         <Output TaskParameter="ConsoleOutput" PropertyName="PaketRestoreCachedHash" />
     </Exec>
-    <Exec Condition=" '$(PaketRestoreLockFileHasher)' != '' " Command="$(PaketRestoreLockFileHasher)" ConsoleToMSBuild='true'>
+    <Exec StandardOutputImportance="Low" Condition=" '$(PaketRestoreLockFileHasher)' != '' " Command="$(PaketRestoreLockFileHasher)" ConsoleToMSBuild='true'>
         <Output TaskParameter="ConsoleOutput" PropertyName="PaketRestoreLockFileHash" />
     </Exec>
 

docs/aggregations/writing-aggregations.asciidoc

@@ -204,7 +204,7 @@ s => s
 
 An advanced scenario may involve an existing collection of aggregation functions that should be set as aggregations
 on the request. Using LINQ's `.Aggregate()` method, each function can be applied to the aggregation descriptor
-`childAggs` below) in turn, returning the descriptor after each function application.
+(`childAggs` below) in turn, returning the descriptor after each function application.
 
 [source,csharp]
 ----
@@ -230,6 +230,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
 
 [[aggs-vs-aggregations]]
@@ -277,5 +278,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/certificates/working-with-certificates.asciidoc

@@ -23,7 +23,8 @@ that generated the certificate is trusted by the machine running the client code
 to the cluster over HTTPS with the client.
 
 If you are using your own CA which is not trusted however, .NET won't allow you to make HTTPS calls to that endpoint by default. With .NET,
-you can pre-empt this though a custom validation callback on the global static`ServicePointManager.ServerCertificateValidationCallback`. Most examples you will find doing this this will simply return `true` from the
+you can pre-empt this though a custom validation callback on the global static
+`ServicePointManager.ServerCertificateValidationCallback`. Most examples you will find doing this this will simply return `true` from the
 validation callback and merrily whistle off into the sunset. **This is not advisable** as it allows *any* HTTPS traffic through in the
 current `AppDomain` *without* any validation. Here's a concrete example:
 
@@ -41,8 +42,9 @@ validation will not be performed for HTTPS connections to *both* Elasticsearch *
 ==== Validation configuration
 
 It's possible to also set a callback per service endpoint with .NET, and both Elasticsearch.NET and NEST expose this through
-connection settings `ConnectionConfiguration` with Elasticsearch.Net and `ConnectionSettings` with NEST). You can do
-your own validation in that handler or use one of the baked in handlers that we ship with out of the box, on the static class`CertificateValidations`.
+connection settings (`ConnectionConfiguration` with Elasticsearch.Net and `ConnectionSettings` with NEST). You can do
+your own validation in that handler or use one of the baked in handlers that we ship with out of the box, on the static class
+`CertificateValidations`.
 
 The two most basic ones are `AllowAll` and `DenyAll`, which accept or deny all SSL traffic to our nodes, respectively. Here's
 a couple of examples.
@@ -83,7 +85,8 @@ If your client application has access to the public CA certificate locally, Elas
 that can assert that a certificate the server presents is one that came from the local CA.
 
 If you use X-Pack's `certgen` tool to {xpack_current}/ssl-tls.html[generate SSL certificates], the generated node certificate
-does not include the CA in the certificate chain, in order to cut down on SSL handshake size. In those case you can use`CertificateValidations.AuthorityIsRoot` and pass it your local copy of the CA public key to assert that
+does not include the CA in the certificate chain, in order to cut down on SSL handshake size. In those case you can use
+`CertificateValidations.AuthorityIsRoot` and pass it your local copy of the CA public key to assert that
 the certificate the server presented was generated using it
 
 [source,csharp]
@@ -121,7 +124,7 @@ through client certificates. The `certgen` tool included with X-Pack allows you
 {ref_current}/certgen.html[generate client certificates as well] and assign the distinguished name (DN) of the
 certificate to a user with a certain role.
 
-certgen by default only generates a public certificate `.cer`) and a private key `.key`. To authenticate with client certificates, you need to present both
+certgen by default only generates a public certificate (`.cer`) and a private key `.key`. To authenticate with client certificates, you need to present both
 as one certificate. The easiest way to do this is to generate a `pfx` or `p12` file from the `.cer` and `.key`
 and attach these to requests using `new X509Certificate(pathToPfx)`.
 
@@ -152,8 +155,11 @@ public class PkiCluster : CertgenCaCluster
 }
 ----
 <1> Set the client certificate on `ConnectionSettings`
+
 <2> The path to the `.cer` file
+
 <3> The path to the `.key` file
+
 <4> The password for the private key
 
 Or per request on `RequestConfiguration` which will take precedence over the ones defined on `ConnectionConfiguration`

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

@@ -22,7 +22,8 @@ NEST can use to issue client calls on.
 
 [IMPORTANT]
 --
-Despite the name, a connection pool in NEST is **not** like connection pooling that you may be familiar with from https://msdn.microsoft.com/en-us/library/bb399543(v=vs.110).aspx[interacting with a database using ADO.Net]; for example,
+Despite the name, a connection pool in NEST is **not** like connection pooling that you may be familiar with from
+https://msdn.microsoft.com/en-us/library/bb399543(v=vs.110).aspx[interacting with a database using ADO.Net]; for example,
 a connection pool in NEST is **not** responsible for managing an underlying pool of TCP connections to Elasticsearch,
 this is https://blogs.msdn.microsoft.com/adarshk/2005/01/02/understanding-system-net-connection-management-and-servicepointmanager/[handled by the ServicePointManager in Desktop CLR]
 and can be controlled by <<servicepoint-behaviour,changing the ServicePoint behaviour>> on `HttpConnection`.

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

@@ -103,7 +103,8 @@ sniffingPipeline.FirstPoolUsageNeedsSniffing.Should().BeFalse();
 
 ==== Wait for first sniff
 
-All threads wait for the sniff on startup to finish, waiting the request timeout period. A https://msdn.microsoft.com/en-us/library/system.threading.semaphoreslim(v=vs.110).aspx[`SemaphoreSlim`]
+All threads wait for the sniff on startup to finish, waiting the request timeout period. A
+https://msdn.microsoft.com/en-us/library/system.threading.semaphoreslim(v=vs.110).aspx[`SemaphoreSlim`]
 is used to block threads until the sniff finishes and waiting threads release the `SemaphoreSlim` appropriately.
 
 We can demonstrate this with the following example. First, let's configure

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

@@ -60,8 +60,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
@@ -100,7 +103,9 @@ audit = await audit.TraceUnexpectedException(
 );
 ----
 <1> calls on 9200 set up to throw 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.
@@ -145,6 +150,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

@@ -68,6 +68,7 @@ var audit = new Auditor(() => Framework.Cluster
 );
 ----
 <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
@@ -88,7 +89,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 does not attempt to deserialize the response body returned;
@@ -122,6 +125,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
@@ -154,5 +158,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/request-overrides/disable-sniff-ping-per-request.asciidoc

@@ -67,8 +67,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 
@@ -92,6 +95,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 
@@ -113,5 +117,6 @@ audit = await audit.TraceCall(
 );
 ----
 <1> diable ping and sniff
+
 <2> no ping or sniff before the call
 

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

@@ -142,7 +142,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 
@@ -192,5 +194,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/role-detection.asciidoc

@@ -140,6 +140,7 @@ var audit = new Auditor(() => Framework.Cluster
 };
 ----
 <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
@@ -220,7 +221,9 @@ var audit = new Auditor(() => Framework.Cluster
 };
 ----
 <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
@@ -297,6 +300,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