[DOCS] restructure java clients docs pages (#25517)

This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.

docs/java-rest/high-level/apis.asciidoc

@@ -1,4 +1,4 @@
-=== Supported APIs
+== Supported APIs
 
 The Java High Level REST Client supports the following APIs:
 

docs/java-rest/high-level/apis/_index.asciidoc

@@ -1,8 +1,8 @@
 [[java-rest-high-document-index]]
-==== Index API
+=== Index API
 
 [[java-rest-high-document-index-request]]
-===== Index Request
+==== Index Request
 
 An `IndexRequest` requires the following arguments:
 
@@ -15,7 +15,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-string]
 <3> Document id
 <4> Document source provided as a `String`
 
-===== Providing the document source
+==== Providing the document source
 The document source can be provided in different ways:
 
 ["source","java",subs="attributes,callouts,macros"]
@@ -39,7 +39,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-shortcut]
 <1> Document source provided as `Object` key-pairs, which gets converted to
 JSON format
 
-===== Optional arguments
+==== Optional arguments
 The following arguments can optionally be provided:
 
 ["source","java",subs="attributes,callouts,macros"]
@@ -94,7 +94,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-pipeline]
 <1> The name of the ingest pipeline to be executed before indexing the document
 
 [[java-rest-high-document-index-sync]]
-===== Synchronous Execution
+==== Synchronous Execution
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -102,7 +102,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute]
 --------------------------------------------------
 
 [[java-rest-high-document-index-async]]
-===== Asynchronous Execution
+==== Asynchronous Execution
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -113,7 +113,7 @@ provided as an argument.
 <2> Called in case of failure. The raised exception is provided as an argument.
 
 [[java-rest-high-document-index-response]]
-===== Index Response
+==== Index Response
 
 The returned `IndexResponse` allows to retrieve information about the executed
  operation as follows:

docs/java-rest/high-level/apis/delete.asciidoc

@@ -1,8 +1,8 @@
 [[java-rest-high-document-delete]]
-==== Delete API
+=== Delete API
 
 [[java-rest-high-document-delete-request]]
-===== Delete Request
+==== Delete Request
 
 A `DeleteRequest` requires the following arguments:
 
@@ -14,7 +14,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request]
 <2> Type
 <3> Document id
 
-===== Optional arguments
+==== Optional arguments
 The following arguments can optionally be provided:
 
 ["source","java",subs="attributes,callouts,macros"]
@@ -56,7 +56,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-version-type
 <1> Version type
 
 [[java-rest-high-document-delete-sync]]
-===== Synchronous Execution
+==== Synchronous Execution
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -64,7 +64,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute]
 --------------------------------------------------
 
 [[java-rest-high-document-delete-async]]
-===== Asynchronous Execution
+==== Asynchronous Execution
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -75,7 +75,7 @@ provided as an argument.
 <2> Called in case of failure. The raised exception is provided as an argument.
 
 [[java-rest-high-document-delete-response]]
-===== Delete Response
+==== Delete Response
 
 The returned `DeleteResponse` allows to retrieve information about the executed
  operation as follows:

docs/java-rest/high-level/index.asciidoc

@@ -1,6 +1,8 @@
 [[java-rest-high]]
-== Java High Level REST Client
+= Java High Level REST Client
 
+[partintro]
+--
 The Java High Level REST Client works on top of the Java Low Level REST client.
 Its main goal is to expose API specific methods, that accept request objects as
 an argument and return response objects, so that request marshalling and
@@ -16,8 +18,12 @@ The Java High Level REST Client depends on the Elasticsearch core project.
 It accepts the same request arguments as the `TransportClient` and returns
 the same response objects.
 
+--
+
 include::usage.asciidoc[]
 
 include::apis.asciidoc[]
 
 include::apis/index.asciidoc[]
+
+include::../license.asciidoc[]

docs/java-rest/high-level/usage.asciidoc

@@ -1,8 +1,11 @@
 [[java-rest-high-usage]]
-=== Getting started
+== Getting started
+
+This section describes how to get started with the high-level REST client from
+getting the artifact to using it in an application.
 
 [[java-rest-high-usage-maven]]
-==== Maven Repository
+=== Maven Repository
 
 The high-level Java REST client is hosted on
 http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.elasticsearch.client%22[Maven
@@ -12,7 +15,7 @@ The High Level REST Client is subject to the same release cycle as
 Elasticsearch. Replace the version with the desired client version.
 
 [[java-rest-high-usage-maven-maven]]
-===== Maven configuration
+==== Maven configuration
 
 Here is how you can configure the dependency using maven as a dependency manager.
 Add the following to your `pom.xml` file:
@@ -27,7 +30,7 @@ Add the following to your `pom.xml` file:
 --------------------------------------------------
 
 [[java-rest-high-usage-maven-gradle]]
-===== Gradle configuration
+==== Gradle configuration
 
 Here is how you can configure the dependency using gradle as a dependency manager.
 Add the following to your `build.gradle` file:
@@ -40,7 +43,7 @@ dependencies {
 --------------------------------------------------
 
 [[java-rest-high-usage-dependencies]]
-==== Dependencies
+=== Dependencies
 
 The High Level Java REST Client depends on the following artifacts and their
 transitive dependencies:
@@ -50,7 +53,7 @@ transitive dependencies:
 
 
 [[java-rest-high-usage-initialization]]
-==== Initialization
+=== Initialization
 
 A `RestHighLevelClient` instance needs a <<java-rest-low-usage-initialization,REST low-level client>>
 to be built as follows:

docs/java-rest/index.asciidoc

@@ -8,5 +8,3 @@ include::overview.asciidoc[]
 include::low-level/index.asciidoc[]
 
 include::high-level/index.asciidoc[]
-
-include::license.asciidoc[]

docs/java-rest/license.asciidoc

@@ -1,4 +1,3 @@
-[[java-rest-license]]
 == License
 
 Copyright 2013-2017 Elasticsearch

docs/java-rest/low-level/configuration.asciidoc

@@ -1,4 +1,4 @@
-=== Common configuration
+== Common configuration
 
 The `RestClientBuilder` supports providing both a `RequestConfigCallback` and
 an `HttpClientConfigCallback` which allow for any customization that the Apache
@@ -8,7 +8,7 @@ configuration that the `RestClient` is initialized with. This section
 describes some common scenarios that require additional configuration for the
 low-level Java REST Client.
 
-==== Timeouts
+=== Timeouts
 
 Configuring requests timeouts can be done by providing an instance of
 `RequestConfigCallback` while building the `RestClient` through its builder.
@@ -34,7 +34,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
         .build();
 --------------------------------------------------
 
-==== Number of threads
+=== Number of threads
 
 The Apache Http Async Client starts by default one dispatcher thread, and a
 number of worker threads used by the connection manager, as many as the number
@@ -55,7 +55,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
         .build();
 --------------------------------------------------
 
-==== Basic authentication
+=== Basic authentication
 
 Configuring basic authentication can be done by providing an
 `HttpClientConfigCallback` while building the `RestClient` through its builder.
@@ -104,7 +104,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
         .build();
 --------------------------------------------------
 
-==== Encrypted communication
+=== Encrypted communication
 
 Encrypted communication can also be configured through the
 `HttpClientConfigCallback`. The
@@ -130,7 +130,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
         .build();
 --------------------------------------------------
 
-==== Others
+=== Others
 
 For any other required configuration needed, the Apache HttpAsyncClient docs
 should be consulted: https://hc.apache.org/httpcomponents-asyncclient-4.1.x/ .

docs/java-rest/low-level/index.asciidoc

@@ -1,5 +1,8 @@
 [[java-rest-low]]
-== Java Low Level REST Client
+= Java Low Level REST Client
+
+[partintro]
+--
 
 The low-level client's features include:
 
@@ -19,9 +22,12 @@ The low-level client's features include:
 
 * optional automatic <<sniffer,discovery of cluster nodes>>
 
+--
 
 include::usage.asciidoc[]
 
 include::configuration.asciidoc[]
 
 include::sniffer.asciidoc[]
+
+include::../license.asciidoc[]

docs/java-rest/low-level/sniffer.asciidoc

@@ -1,5 +1,5 @@
 [[sniffer]]
-=== Sniffer
+== Sniffer
 
 Minimal library that allows to automatically discover nodes from a running
 Elasticsearch cluster and set them to an existing `RestClient` instance.
@@ -8,7 +8,7 @@ Nodes Info api and uses jackson to parse the obtained json response.
 
 Compatible with Elasticsearch 2.x and onwards.
 
-==== Maven Repository
+=== Maven Repository
 
 The low-level REST client is subject to the same release cycle as
 elasticsearch. Replace the version with the desired sniffer version, first
@@ -17,7 +17,7 @@ and the elasticsearch version that the client can communicate with. Sniffer
 supports fetching the nodes list from elasticsearch 2.x and onwards.
 
 
-===== Maven configuration
+==== Maven configuration
 
 Here is how you can configure the dependency using maven as a dependency manager.
 Add the following to your `pom.xml` file:
@@ -31,7 +31,7 @@ Add the following to your `pom.xml` file:
 </dependency>
 --------------------------------------------------
 
-===== Gradle configuration
+==== Gradle configuration
 
 Here is how you can configure the dependency using gradle as a dependency manager.
 Add the following to your `build.gradle` file:
@@ -43,7 +43,7 @@ dependencies {
 }
 --------------------------------------------------
 
-==== Usage
+=== Usage
 
 Once a `RestClient` instance has been created, a `Sniffer` can be associated
 to it. The `Sniffer` will make use of the provided `RestClient` to periodically
@@ -132,20 +132,3 @@ Sniffer sniffer = Sniffer.builder(restClient)
 
 Note that this last configuration parameter has no effect in case sniffing
 on failure is not enabled like explained above.
-
-==== License
-
-Copyright 2013-2017 Elasticsearch
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-

docs/java-rest/low-level/usage.asciidoc

@@ -1,8 +1,11 @@
 [[java-rest-low-usage]]
-=== Getting started
+== Getting started
+
+This section describes how to get started with the low-level REST client from
+getting the artifact to using it in an application.
 
 [[java-rest-low-usage-maven]]
-==== Maven Repository
+=== Maven Repository
 
 The low-level Java REST client is hosted on
 http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.elasticsearch.client%22[Maven
@@ -15,7 +18,7 @@ and the elasticsearch version that the client can communicate with. The
 low-level REST client is compatible with all elasticsearch versions.
 
 [[java-rest-low-usage-maven-maven]]
-===== Maven configuration
+==== Maven configuration
 
 Here is how you can configure the dependency using maven as a dependency manager.
 Add the following to your `pom.xml` file:
@@ -30,7 +33,7 @@ Add the following to your `pom.xml` file:
 --------------------------------------------------
 
 [[java-rest-low-usage-maven-gradle]]
-===== Gradle configuration
+==== Gradle configuration
 
 Here is how you can configure the dependency using gradle as a dependency manager.
 Add the following to your `build.gradle` file:
@@ -43,7 +46,7 @@ dependencies {
 --------------------------------------------------
 
 [[java-rest-low-usage-dependencies]]
-==== Dependencies
+=== Dependencies
 
 The low-level Java REST client internally uses the
 http://hc.apache.org/httpcomponents-asyncclient-dev/[Apache Http Async Client]
@@ -59,7 +62,7 @@ http://hc.apache.org/httpcomponents-asyncclient-dev/[Apache Http Async Client]
 
 
 [[java-rest-low-usage-initialization]]
-==== Initialization
+=== Initialization
 
 A `RestClient` instance can be built through the corresponding
 `RestClientBuilder` class, created via `RestClient#builder(HttpHost...)`
@@ -108,7 +111,7 @@ http://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/
 
 
 [[java-rest-low-usage-requests]]
-==== Performing requests
+=== Performing requests
 
 Once the `RestClient` has been created, requests can be sent by calling one of
 the available `performRequest` or `performRequestAsync` method variants.
@@ -167,7 +170,7 @@ void performRequestAsync(String method, String endpoint,
 --------------------------------------------------
 
 [[java-rest-low-usage-requests-arguments]]
-===== Request Arguments
+==== Request Arguments
 
 The following are the arguments accepted by the different methods:
 
@@ -188,7 +191,7 @@ request success or failure
 `headers`:: optional request headers
 
 [[java-rest-low-usage-responses]]
-==== Reading responses
+=== Reading responses
 
 The `Response` object, either returned by the synchronous `performRequest` methods or
 received as an argument in `ResponseListener#onSuccess(Response)`, wraps the
@@ -226,7 +229,7 @@ response, just without the document as it was not found.
 
 
 [[java-rest-low-usage-example]]
-==== Example requests
+=== Example requests
 
 Here are a couple of examples:
 
@@ -304,7 +307,7 @@ latch.await();
 --------------------------------------------------
 
 [[java-rest-low-usage-logging]]
-==== Logging
+=== Logging
 
 The Java REST client uses the same logging library that the Apache Async Http
 Client uses: https://commons.apache.org/proper/commons-logging/[Apache Commons Logging],

docs/java-rest/overview.asciidoc

@@ -1,11 +1,13 @@
 [[java-rest-overview]]
 == Overview
 
-The Java REST Client comes with 2 flavors:
+The Java REST Client comes in 2 flavors:
 
-* <<java-rest-low>>: which is the official low-level client for Elasticsearch.
-It allows to communicate with an Elasticsearch cluster through http and is compatible
-with all elasticsearch versions.
+* <<java-rest-low>>: the official low-level client for Elasticsearch.
+It allows to communicate with an Elasticsearch cluster through http.
+Leaves requests marshalling and responses un-marshalling to users.
+It is compatible with all Elasticsearch versions.
 
-* <<java-rest-high>>: which is the official high-level client for Elasticsearch. It adds support
-part of the elasticsearch document level and search API on top of the low-level client.
+* <<java-rest-high>>: the official high-level client for Elasticsearch.
+Based on the low-level client, it exposes API specific methods and takes care
+of requests marshalling and responses un-marshalling.