[DOCS] Reorganizes Overview and Installation chapters

docs/index.asciidoc

@@ -1,118 +1,6 @@
-= elasticsearch
+= Elasticsearch Rust Client
 
-An official Rust client for Elasticsearch.
+include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
-== Overview
-
-Full documentation is hosted at https://docs.rs/elasticsearch[docs.rs]
--- this page provides _only_ an overview.
-
-=== Elasticsearch Version Compatibility
-
-|===
-| Rust client | Elasticsearch
-| 7.x         | 7.x
-|===
-
-A major version of the client is compatible with the same major version of Elasticsearch.
-Since Elasticsearch is developed following https://semver.org/[Semantic Versioning] principles,
-Any minor/patch version of the client can be used against any minor/patch version of Elasticsearch
-**within the same major version lineage**. For example,
-
-- A `7.5.0` client can be used against `7.0.0` Elasticsearch
-- A `7.5.0` client can be used against `7.6.0` Elasticsearch
-
-In the former case, a 7.5.0 client may contain additional API functions that are not available
-in 7.0.0 Elasticsearch. In this case, these APIs cannot be used, but for any APIs available in
-Elasticsearch, the respective API functions on the client will be compatible.
-
-In the latter case, a 7.5.0 client won't contain API functions for APIs that are introduced in
-Elasticsearch 7.6.0+, but for all other APIs available in Elasticsearch, the respective API
-functions on the client will be compatible.
-
-**No compatibility assurances are given between different major versions of the client and
-Elasticsearch**. Major differences likely exist between major versions of Elasticsearch, particularly
-around request and response object formats, but also around API urls and behaviour.
-
-=== Installing
-
-Add `elasticsearch` crate and version to Cargo.toml. Choose the version
-that is compatible with the version of Elasticsearch you're using
-
-[source,toml]
-----
-[dependencies]
-elasticsearch = "8.0.0-alpha.1"
-----
-
-The following _optional_ dependencies may also be useful to create requests and read responses
-
-[source,toml]
-----
-serde = "~1"
-serde_json = "~1"
-----
-
-=== Create a client
-
-To create a client to make API calls to Elasticsearch running on `\http://localhost:9200`
-
-[source,rust]
-----
-let client = Elasticsearch::default();
-----
-
-Alternatively, you can create a client to make API calls against Elasticsearch running on a
-specific `url::Url`
-
-[source,rust]
-----
-let transport = Transport::single_node("https://example.com")?;
-let client = Elasticsearch::new(transport);
-----
-
-If you're running against an Elasticsearch deployment in https://www.elastic.co/cloud/[Elastic Cloud],
-a client can be created using a https://www.elastic.co/guide/en/cloud/current/ec-cloud-id.html[Cloud ID]
-and credentials retrieved from the Cloud web console
-
-[source,rust]
-----
-let cloud_id = "<cloud id from cloud web console>";
-let credentials = Credentials::Basic("<username>".into(), "<password>".into());
-let transport = Transport::cloud(cloud_id, credentials)?;
-let client = Elasticsearch::new(transport);
-----
-
-=== Making API calls
-
-The following makes an API call to `tweets/_search` with the json body
-`{"query":{"match":{"message":"Elasticsearch"}}}`
-
-[source,rust]
-----
-let response = client
-    .search(SearchParts::Index(&["tweets"]))
-    .from(0)
-    .size(10)
-    .body(json!({
-        "query": {
-            "match": {
-                "message": "Elasticsearch rust"
-            }
-        }
-    }))
-    .send()
-    .await?;
-
-let response_body = response.json::<Value>().await?;
-let took = response_body["took"].as_i64().unwrap();
-for hit in response_body["hits"]["hits"].as_array().unwrap() {
-    // print the source document
-    println!("{:?}", hit["_source"]);
-}
-----
-
-== Resources
-
-* https://github.com/elastic/elasticsearch-rs[Source code]
-* https://docs.rs/elasticsearch[API documentation]
+include::overview.asciidoc[]
+include::installation.asciidoc[]

docs/installation.asciidoc

@@ -0,0 +1,20 @@
+[[installation]]
+== Installation
+
+Add `elasticsearch` crate and version to Cargo.toml. Choose the version that is 
+compatible with the version of {es} you are using:
+
+[source,toml]
+----
+[dependencies]
+elasticsearch = "8.0.0-alpha.1"
+----
+
+The following _optional_ dependencies may also be useful to create requests and 
+read responses:
+
+[source,toml]
+----
+serde = "~1"
+serde_json = "~1"
+----

docs/overview.asciidoc

@@ -0,0 +1,116 @@
+[[overview]]
+== Overview
+
+This is the official Rust client for {es}. Full documentation is hosted on 
+https://docs.rs/elasticsearch[docs.rs] -- this page provides _only_ an overview.
+
+Further resources:
+
+* https://github.com/elastic/elasticsearch-rs[Source code]
+* https://docs.rs/elasticsearch[API documentation]
+
+
+[discrete]
+[[features]]
+=== Features
+
+* Fluent builders for all {es} REST API endpoints
+* Persistent keep-alive connections
+* TLS support with system or custom certificates
+* Proxy support with authentication
+* Async support with Tokio
+
+
+[discrete]
+=== {es} Version Compatibility
+
+|===
+| Rust client | Elasticsearch
+| 7.x         | 7.x
+|===
+
+A major version of the client is compatible with the same major version of {es}.
+Since {es} is developed following https://semver.org/[Semantic Versioning] 
+principles, any minor/patch version of the client can be used against any 
+minor/patch version of {es} **within the same major version lineage**. For 
+example,
+
+- A `7.5.0` client can be used against `7.0.0` Elasticsearch
+- A `7.5.0` client can be used against `7.6.0` Elasticsearch
+
+In the former case, a 7.5.0 client may contain additional API functions that are 
+not available in 7.0.0 {es}. In this case, these APIs cannot be used, but for 
+any APIs available in {es}, the respective API functions on the client will be 
+compatible.
+
+In the latter case, a 7.5.0 client won't contain API functions for APIs that are 
+introduced in {es} 7.6.0+, but for all other APIs available in {es}, the 
+respective API functions on the client will be compatible.
+
+**No compatibility assurances are given between different major versions of the 
+client and {es}.** Major differences likely exist between major versions of 
+{es}, particularly around request and response object formats, but also around 
+API urls and behaviour.
+
+
+[discrete]
+=== Create a client
+
+To create a client to make API calls to Elasticsearch running on `\http://localhost:9200`
+
+[source,rust]
+----
+let client = Elasticsearch::default();
+----
+
+Alternatively, you can create a client to make API calls against Elasticsearch running on a
+specific `url::Url`
+
+[source,rust]
+----
+let transport = Transport::single_node("https://example.com")?;
+let client = Elasticsearch::new(transport);
+----
+
+If you're running against an Elasticsearch deployment in https://www.elastic.co/cloud/[Elastic Cloud],
+a client can be created using a https://www.elastic.co/guide/en/cloud/current/ec-cloud-id.html[Cloud ID]
+and credentials retrieved from the Cloud web console
+
+[source,rust]
+----
+let cloud_id = "<cloud id from cloud web console>";
+let credentials = Credentials::Basic("<username>".into(), "<password>".into());
+let transport = Transport::cloud(cloud_id, credentials)?;
+let client = Elasticsearch::new(transport);
+----
+
+
+[discrete]
+=== Making API calls
+
+The following makes an API call to `tweets/_search` with the json body
+`{"query":{"match":{"message":"Elasticsearch"}}}`
+
+[source,rust]
+----
+let response = client
+    .search(SearchParts::Index(&["tweets"]))
+    .from(0)
+    .size(10)
+    .body(json!({
+        "query": {
+            "match": {
+                "message": "Elasticsearch rust"
+            }
+        }
+    }))
+    .send()
+    .await?;
+
+let response_body = response.json::<Value>().await?;
+let took = response_body["took"].as_i64().unwrap();
+for hit in response_body["hits"]["hits"].as_array().unwrap() {
+    // print the source document
+    println!("{:?}", hit["_source"]);
+}
+----