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 elastic#2248

(cherry-picked from commit 6268353)

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
                         ]
                  }