Switch .net client to Asciidoctor

[nik9000]

Switches the core of the docs build for the Elasticsearch client for
.net from the unmaintained AsciiDoc project to the actively maintained
Asciidoctor project.

[nik9000]

OK! This one hits this Asciidoctor feature that automatically splits titles that contain a : into a title and a subtitle. We can stop this by switching the : to some other character like so:

diff --git a/docs/index.asciidoc b/docs/index.asciidoc
index a1f4be86e..67143355d 100644
--- a/docs/index.asciidoc
+++ b/docs/index.asciidoc
@@ -1,3 +1,5 @@
+:title-separator: |
+
 [[elasticsearch-net-reference]]
 = Elasticsearch.Net and NEST:  the .NET clients
 

But if we actually want the subtitle we can just switch to asciidoctor without making this change. Having the subtitle makes two changes:

1. On the title page with the table of contents the title is rendered like this:
   
   instead of
   

2. The subtitle is missing from the breadcrumbs so they look like:
   
   instead of
   

Personally I think this is an improvement which is why I suggested keeping it but I'm fine to be told it isn't.

[nik9000]

There is one other difference that seems to be caused by a missing attribute:
working-with-certificates.html: (5.x branch, probably others)

- AsciiDoc
+ Asciidoctor
@@ -813,7 +813,11 @@
              If your client application has access to the public CA certificate locally, Elasticsearch.NET and NEST ship with some handy helpers that can assert that a certificate the server presents is one that came from the local CA.
             </p>
             <p>
-             does not include the CA in the certificate chain, in order to cut down on SSL handshake size. In those case you can use
+             If you use X-Pack’s
+             <code class="literal">
+              certgen
+             </code>
+             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
              <code class="literal">
               CertificateValidations.AuthorityIsRoot
              </code>
@@ -873,7 +877,7 @@
             </div>
            </div>
            <p>
-            through client certificates. The
+            X-Pack also allows you to configure a {xpack_current}/pki-realm.html[PKI realm] to enable user authentication through client certificates. The
             <code class="literal">
              certgen
             </code>

The xpack_current attribute is missing and I've got Asciidoctor configured to render the attribute name rather than drop the line. It is likely worth fixing the attribute.

[nik9000]

1.x has a few missing attributes:
breaking-changes.html:

- AsciiDoc
+ Asciidoctor
@@ -641,7 +641,7 @@
            </a>
           </h3>
           <p>
-           The outer layer of NEST has been completely rewritten from scratch. Many calls will now have a different signature. Although the most common ones have been Two notable changes should be outlined though.
+           The outer layer of NEST has been completely rewritten from scratch. Many calls will now have a different signature. Although the most common ones have been reimplemented as {github}/tree/1.x/src/Nest/ConvenienceExtensions[extensions methods]. Two notable changes should be outlined though.
           </p>
           <h3>
            <a id="_renamed_get_to_source_removed_getfull">
@@ -1057,6 +1057,7 @@
            </a>
           </h2>
           <p>
+           If you found another breaking chage please let us know on {github}/issues[the github issues].
           </p>
          </div>
          <div class="navfooter">

percentiles-aggregation.html:

- AsciiDoc
+ Asciidoctor
@@ -635,6 +635,7 @@
 var agg = result.Aggs.Percentiles("my_percentiles_agg");</pre>
           </div>
           <p>
+           Refer to the {ref_current}/search-aggregations-metrics-percentile-aggregation.html[original docs] for more information.
           </p>
          </div>
          <div class="navfooter">

[nik9000]

@russcam and @lcawl, what do you think about the subtitle? Would you like to use the subtitle or would you like to disable it?

[lcawl]

If Russ likes it, it's fine by me. Though I'd capitalize "The".

[russcam]

@nik9000 The intention was always to have the subtitle, but looking at the breadcrumbs, I think it'd be better to keep the .NET clients as part of the title i.e. change the escape character as suggested, or change the : to not render as a subtitle.

I'll add the missing attributes.

[russcam]

I've added the missing attributes flagged above.

[russcam]

Change to title separator LGTM. Alternatively, we can change in the doc files to not render as a subtitle.

[nik9000]

I've added the missing attributes flagged above.

Thanks!

Change to title separator LGTM. Alternatively, we can change in the doc files to not render as a subtitle.

@russcam, I opened elastic/elasticsearch-net#3676

[nik9000]

@russcam merged elastic/elasticsearch-net#3676 so I've merged this to get us building in Asciidoctor!