Overhaul client documentation

- Introduce additional TOC level and simplify asciidoc structure
- Use MsBuildWorkspace to get the ASTs of each document of interest.
  This will allow us to query the Semantic Model to obtain richer information for doc generation
- Refactor source code walking
  Simplified walking into a base walker implementation that can be modified by a derived walker to perform different actions on syntax nodes e.g. usage tests apply conventions for Fluent, Object Initializer API examples with JSON output.
- Process attribute entries found within document bodies to generate and include asciidoc elements within the document.
- Generate XML documentation file from the compilation of the Elasticsearch.Net and NEST projects.
  Could refactor current implementation further to extract all comments using Roslyn without taking a dependency on NuDoq.
- Update the naming of query usage tests to be consistent; these are used as headers in the table of contents
- Introduce sections for
  - Getting started with NEST
  - Getting started with Elasticsearch.Net
  - Configuration options from XML docs for ConnectionSettings
  - Modifying serialization
  - Using Client certificates
  - Writing Analyzers
  - Testing Analyzers
  - Writing queries
  - Improve Writing bool queries
  - Logging
  - Debugging

Part of #2248

Author: russcam

build/scripts/Building.fsx

@@ -53,8 +53,8 @@ module Build =
         )
 
     let private compileDesktop() =
-        Tooling.MsBuild.Rebuild DotNetFramework.Net45.Identifier
-        Tooling.MsBuild.Rebuild DotNetFramework.Net46.Identifier
+        Tooling.MsBuild.Rebuild DotNetFramework.Net45
+        Tooling.MsBuild.Rebuild DotNetFramework.Net46
 
     let private gitLink() =
         DotNetProject.AllPublishable
@@ -70,7 +70,7 @@ module Build =
 
     let Compile() = 
         match quickBuild with 
-        | true ->  Tooling.MsBuild.Build DotNetFramework.Net45.Identifier
+        | true ->  Tooling.MsBuild.Build DotNetFramework.Net45
         | false ->  
             compileDesktop()
             compileCore()

build/scripts/Tooling.fsx

@@ -158,9 +158,16 @@ module Tooling =
     let DotNet = new DotNetTooling("dotnet.exe")
 
     type MsBuildTooling() =
-
-        member this.Build (framework:Projects.DotNetFrameworkIdentifier) =
-            let solution = Paths.Source "Elasticsearch.sln";
+        // Exclude DocGenerator from .NET 4.5 build as it depends on a Roslyn library
+        // that is built against .NET 4.5.2
+        let solutionForFramework framework =
+            match framework with
+            | Net45 -> Paths.Source "Elasticsearch.Net45.sln"
+            | _ -> Paths.Source "Elasticsearch.sln"  
+
+        member this.Build (framework:Projects.DotNetFramework) =            
+            let solution = solutionForFramework framework 
+            let identifier = framework.Identifier
             let setParams defaults =
                 { defaults with
                     Verbosity = Some(Quiet)
@@ -169,14 +176,15 @@ module Tooling =
                         [
                             "Optimize", "True"
                             "Configuration", "Release"
-                            "TargetFrameworkVersion", framework.MSBuild
-                            "DefineConstants", framework.DefineConstants
+                            "TargetFrameworkVersion", identifier.MSBuild
+                            "DefineConstants", identifier.DefineConstants
                         ]
                  }
             build setParams solution 
 
-        member this.Rebuild (framework:Projects.DotNetFrameworkIdentifier) =
-            let solution = Paths.Source "Elasticsearch.sln";
+        member this.Rebuild (framework:Projects.DotNetFramework) = 
+            let solution = solutionForFramework framework              
+            let identifier = framework.Identifier               
             let setParams defaults =
                 { defaults with
                     Verbosity = Some(Quiet)
@@ -186,8 +194,8 @@ module Tooling =
                             "OutputPathBaseDir", Path.GetFullPath "build\\output"
                             "Optimize", "True"
                             "Configuration", "Release"
-                            "TargetFrameworkVersion", framework.MSBuild
-                            "DefineConstants", framework.DefineConstants
+                            "TargetFrameworkVersion", identifier.MSBuild
+                            "DefineConstants", identifier.DefineConstants
                         ]
                  }
 

docs/5.0-breaking-changes/elasticsearch-net-breaking-changes.asciidoc

@@ -1,7 +1,7 @@
 [[elasticsearch-net-breaking-changes]]
 == Elasticsearch.Net Breaking Changes
 
-This lists all the *binary* breaking changes in Elasticsearch.Net.
+This lists all the *binary* breaking changes in Elasticsearch.Net from 2.x to 5.x.
 
 [float]
 [[enums]]
@@ -165,6 +165,7 @@ _Declaration changed (Breaking)_ +
 *public method Elasticsearch.Net.UpdateRequestParameters.Refresh*
 _Declaration changed (Breaking)_
 
+
 [float]
 [[waitforactiveshards-now-takes-a-string]]
 === WaitForActiveShards now takes a string
@@ -341,7 +342,7 @@ _Declaration changed (Breaking)_
 [[removed-in-5.x-after-obsolete-period]]
 === Removed in 5.x after obsolete period
 
-These are types/properties/methods marked obsolete in NEST 2.x that have
+These are types/properties/methods marked obsolete in Elasticsearch.Net 2.x that have
 now been removed.
 
 *public method Elasticsearch.Net.AnalyzeRequestParameters.Analyzer*

docs/5.0-breaking-changes/nest-breaking-changes.asciidoc

@@ -2,9 +2,9 @@
 == NEST Breaking Changes
 
 Oh my goodness, this looks like a lot of breaking changes! This is true
-but please take note that this list is very very extensive It includes
-every single _binary_ breaking change. In a lot of cases these will not
-necessarily equate to compiler errors.
+but please take note that this list is very extensive and includes
+*every* single _binary_ breaking change. In a lot of cases, these will not
+necessarily equate to compiler errors nor changes in your codebase.
 
 [float]
 [[statsaggregator-renamed-to-statsaggregation]]
@@ -430,6 +430,8 @@ TIndexSettings>.AutoExpandReplicas* _Declaration changed (Breaking)_
 [[dslprettyprintvisitor-methods-are-now-virtual]]
 === DslPrettyPrintVisitor methods are now virtual
 
+This change means that you only need to override the methods that you wish to change the implementation for.
+
 [float]
 [[nest-visitors-should-be-bound-to-interface]]
 === Nest visitors should be bound to interface
@@ -1032,8 +1034,8 @@ also the hacks from 2.x have been removed
 === Allow source filter to send false
 
 In NEST 2.x we would always send Source.Exclude as
-`_source: { exclude: [""] }` in 5.x the we use a union of `bool`
-`ISourceFiler` so NEST can send and recieve `_source: false`. Which
+`_source: { exclude: [""] }`. in 5.x, we now use a union of `bool` and
+`ISourceFiler`, so NEST can send and receive `_source: false`. Which
 should short circuit some routines on the server
 
 See also: https://github.com/elastic/elasticsearch-net/pull/2200[github PR 2200]
@@ -1493,8 +1495,8 @@ public enum StringFielddataFormat
 [[uncategorized]]
 === Uncategorized
 
-Misc. changes that are yet to be categorized. Please open an issue if
-you are bit by these and feel it warrants an explanation.
+Miscellaneous changes that are yet to be categorized. Please open an issue if
+you are bitten by any of these and feel it warrants an explanation.
 
 *public method Nest.DeleteByQueryDescriptor<T>.Routing* _Declaration
 changed (Breaking)_
@@ -1920,12 +1922,11 @@ TValue>.BackingDictionary* +
 
 [float]
 [[nest-cancellationtoken]]
-CancellationToken
------------------
+=== CancellationToken
 
-With NEST 2.x async methods, a cancellation tokens could be passed as
-part of the RequestConfiguration. This was not very discoverable and so
-each async method can now accept an optional cancellation token as an
+With NEST 2.x async methods, a cancellation token could be passed as
+part of the `RequestConfiguration` on the request. This was not very discoverable and so
+each async method now accepts an optional `CancellationToken` as an
 argument, making the API more async idiomatic.
 
 *Nest.BulkAllObservable<T>..ctor* +