Doc updates (#791)

delvedor · web-flow · commit ad6f56c3f1e5 · 2019-03-27T07:44:19.000+01:00
Updates for better displaying the documentation in the website.
diff --git a/docs/authentication.asciidoc b/docs/authentication.asciidoc
@@ -1,8 +1,8 @@
-= Authentication
+== Authentication
 
 This document contains code snippets to show you how to connect to various Elasticsearch providers.
 
-== Basic Auth
+=== Basic Auth
 
 You can provide your credentials in the node(s) URL.
 
@@ -29,7 +29,7 @@ const client = new Client({
 })
 ----
 
-== SSL configuration
+=== SSL configuration
 
 Without any additional configuration you can specify `https://` node urls, but the certificates used to sign these requests will not verified (`rejectUnauthorized: false`). To turn on certificate verification you must specify an `ssl` object either in the top level config or in each host config object and set `rejectUnauthorized: true`. The ssl config object can contain many of the same configuration options that https://nodejs.org/api/tls.html#tls_tls_connect_options_callback[tls.connect()] accepts.
 
@@ -45,7 +45,7 @@ const client = new Client({
 })
 ----
 
-== Elastic Cloud
+=== Elastic Cloud
 
 If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers a easy way to connect to it via the `cloud` option. +
 You must pass the Cloud ID that you can find in the cloud console, then your username and password.
diff --git a/docs/breaking-changes.asciidoc b/docs/breaking-changes.asciidoc
@@ -1,4 +1,4 @@
-= Breaking changes coming from the old client
+== Breaking changes coming from the old client
 
 If you were already using the previous version of this client --i.e. the one you used to install with `npm install elasticsearch`-- you will encounter some breaking changes.
 
diff --git a/docs/child.asciidoc b/docs/child.asciidoc
@@ -1,4 +1,4 @@
-= Creating a child client
+== Creating a child client
 
 There are some use cases where you may need multiple instances of the client. You can easily do that by calling `new Client()` as many times as you need, but you will lose all the benefits of using one single client, such as the long living connections and the connection pool handling. +
 To avoid this problem the client offers a `child` API, which returns a new client instance that shares the connection pool with the parent client. +
diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc
@@ -1,4 +1,4 @@
-= Client configuration
+== Client configuration
 
 The client is designed to be easily configured as you see fit for your needs, following you can see all the possible basic options that you can use to configure it.
 
@@ -14,7 +14,7 @@ const client = new Client({
 })
 ----
 
-== Basic options
+=== Basic options
 [cols=2*]
 |===
 |`node` or `nodes`
@@ -72,7 +72,7 @@ _Default:_ `false`
 
 |`resurrectStrategy`
 |`string` - Configure the node resurrection strategy. +
-_Options:_ `'ping'`, `'optimistic'`, `'none'` +
+_Options:_ `'ping'`, `'optimistic'`, `'none'` +
 _Default:_ `'ping'`
 
 |`suggestCompression`
@@ -122,7 +122,7 @@ function nodeSelector (connections) {
 ----
 |===
 
-== Advanced configuration
+=== Advanced configuration
 If you need to customize the client behavior heavily, you are in the right place! +
 The client allows you to customize the following internals:
 
diff --git a/docs/examples/asStream.asciidoc b/docs/examples/asStream.asciidoc
@@ -1,3 +1,4 @@
+[[as_stream_examples]]
 == asStream
 
 Instead of getting the parsed body back, you will get the raw Node.js stream of data.
diff --git a/docs/examples/bulk.asciidoc b/docs/examples/bulk.asciidoc
@@ -1,4 +1,5 @@
-= Bulk
+[[bulk_examples]]
+== Bulk
 
 The `bulk` API makes it possible to perform many index/delete operations in a single API call. +
 This can greatly increase the indexing speed.
diff --git a/docs/examples/exists.asciidoc b/docs/examples/exists.asciidoc
@@ -1,4 +1,5 @@
-= Exists
+[[exists_examples]]
+== Exists
 
 Check that the document `/game-of-thrones/1` exists.
 
diff --git a/docs/examples/get.asciidoc b/docs/examples/get.asciidoc
@@ -1,4 +1,5 @@
-= Get
+[[get_examples]]
+== Get
 
 The get API allows to get a typed JSON document from the index based on its id. +
 The following example gets a JSON document from an index called `game-of-thrones`, under a type called `_doc`, with id valued `'1'`.
diff --git a/docs/examples/ignore.asciidoc b/docs/examples/ignore.asciidoc
@@ -1,3 +1,4 @@
+[[ignore_examples]]
 == Ignore
 HTTP status codes which should not be considered errors for this request.
 
diff --git a/docs/examples/index.asciidoc b/docs/examples/index.asciidoc
@@ -0,0 +1,28 @@
+[[examples]]
+= Examples
+
+Following you can find some examples on how to use the client.
+
+* Use of the <<as_stream_examples,asStream>> parameter;
+* Executing a <<bulk_examples,bulk>> request;
+* Executing a <<exists_examples,exists>> request;
+* Executing a <<get_examples,get>> request;
+* Use of the <<ignore_examples,ignore>> parameter;
+* Executing a <<msearch_examples,msearch>> request;
+* How do I <<scroll_examples,scroll>>?
+* Executing a <<search_examples,search>> request;
+* I need <<suggest_examples,suggestions>>;
+* How to use the <<transport_request_examples,transport.request>> method;
+* How to use <<typescript_examples,TypeScript>>;
+
+include::asStream.asciidoc[]
+include::bulk.asciidoc[]
+include::exists.asciidoc[]
+include::get.asciidoc[]
+include::ignore.asciidoc[]
+include::msearch.asciidoc[]
+include::scroll.asciidoc[]
+include::search.asciidoc[]
+include::suggest.asciidoc[]
+include::transport.request.asciidoc[]
+include::typescript.asciidoc[]
diff --git a/docs/examples/msearch.asciidoc b/docs/examples/msearch.asciidoc
@@ -1,4 +1,5 @@
-= MSearch
+[[msearch_examples]]
+== MSearch
 
 The multi search API allows to execute several search requests within the same API. 
 
diff --git a/docs/examples/scroll.asciidoc b/docs/examples/scroll.asciidoc
@@ -1,4 +1,5 @@
-= Scroll
+[[scroll_examples]]
+== Scroll
 
 While a search request returns a single “page” of results, the scroll API can be used to retrieve large numbers of results (or even all results) from a single search request, in much the same way as you would use a cursor on a traditional database.
 
diff --git a/docs/examples/search.asciidoc b/docs/examples/search.asciidoc
@@ -1,4 +1,5 @@
-= Search
+[[search_examples]]
+== Search
 
 The `search` API allows you to execute a search query and get back search hits that match the query. +
 The query can either be provided using a simple https://www.elastic.co/guide/en/elasticsearch/reference/6.6/search-uri-request.html[query string as a parameter], or using a https://www.elastic.co/guide/en/elasticsearch/reference/6.6/search-request-body.html[request body].
diff --git a/docs/examples/suggest.asciidoc b/docs/examples/suggest.asciidoc
@@ -1,4 +1,5 @@
-= Suggest
+[[suggest_examples]]
+== Suggest
 
 The suggest feature suggests similar looking terms based on a provided text by using a suggester. _Parts of the suggest feature are still under development._
 
diff --git a/docs/examples/transport.request.asciidoc b/docs/examples/transport.request.asciidoc
@@ -1,4 +1,5 @@
-= transport.request
+[[transport_request_examples]]
+== transport.request
 
 It can happen that you need to communicate with Elasticsearch by using an API that is not supported by the client, to mitigate this issue you can directly call `client.transport.request`, which is the internal utility that the client uses to communicate with Elasticsearch when you use an API method.
 
diff --git a/docs/examples/typescript.asciidoc b/docs/examples/typescript.asciidoc
@@ -1,4 +1,5 @@
-= Typescript
+[[typescript_examples]]
+== Typescript
 
 The client offers a first-class support for TypeScript, since it ships the type definitions for every exposed API.
 
diff --git a/docs/extend.asciidoc b/docs/extend.asciidoc
@@ -1,4 +1,4 @@
-= Extend the client
+== Extend the client
 
 Sometimes you need to reuse the same logic, or you want to build a custom API to allow you simplify your code. +
 The easiest way to achieve that is by extending the client.
diff --git a/docs/index.asciidoc b/docs/index.asciidoc
@@ -1,51 +1,12 @@
 = @elastic/elasticsearch
 
-The official Node.js client for Elasticsearch.
-
-== Features
-* One-to-one mapping with REST API.
-* Generalized, pluggable architecture.
-* Configurable, automatic discovery of cluster nodes.
-* Persistent, Keep-Alive connections.
-* Load balancing (with pluggable selection strategy) across all available nodes.
-* TypeScript support out of the box.
-
-== Install
-[source,sh]
-----
-npm install @elastic/elasticsearch
-----
-By default the latest version of the module will be installed, which is the same version of the current release of Elasticsearch. +
-If you need to work with older versions of Elasticsearch, you should install the same version of the client as well. +
-For example, if you are using Elasticsearch `v6.5.4`, you will need the client `v6`, and you can easily do that with `npm install @elastic/elasticsearch@6`.
-
-== Usage
-[source,js]
-----
-const { Client } = require('@elastic/elasticsearch')
-const client = new Client({ node: 'http://localhost:9200' })
-
-// promise API
-const result = await client.search({
-  index: 'my-index',
-  body: { foo: 'bar' }
-})
-
-// callback API
-client.search({
-  index: 'my-index',
-  body: { foo: 'bar' }
-}, (err, result) => {
-  if (err) console.log(err)
-})
-----
-
-== Reference
-* Client configuration
-* Client usage
-* API methods
-* TypeScript support
-* Extend the client
-* Breaking changes from old client
-* Authentication
-* Child client
+include::introduction.asciidoc[]
+include::usage.asciidoc[]
+include::configuration.asciidoc[]
+include::reference.asciidoc[]
+include::breaking-changes.asciidoc[]
+include::authentication.asciidoc[]
+include::child.asciidoc[]
+include::extend.asciidoc[]
+include::typescript.asciidoc[]
+include::examples/index.asciidoc[]
diff --git a/docs/introduction.asciidoc b/docs/introduction.asciidoc
@@ -0,0 +1,52 @@
+== Introduction
+
+The official Node.js client for Elasticsearch.
+
+=== Features
+* One-to-one mapping with REST API.
+* Generalized, pluggable architecture.
+* Configurable, automatic discovery of cluster nodes.
+* Persistent, Keep-Alive connections.
+* Load balancing (with pluggable selection strategy) across all available nodes.
+* TypeScript support out of the box.
+
+=== Install
+[source,sh]
+----
+npm install @elastic/elasticsearch
+----
+
+=== Compatibility
+
+The library is compatible with all Elasticsearch versions since 5.x, but you should use the same major version of the Elasticsearch instance that you are using.
+----
+# Elasticsearch 7.x
+@elastic/elasticsearch@7
+
+# Elasticsearch 6.x
+@elastic/elasticsearch@6
+
+# Elasticsearch 5.x
+@elastic/elasticsearch@5
+----
+
+=== Usage
+[source,js]
+----
+const { Client } = require('@elastic/elasticsearch')
+const client = new Client({ node: 'http://localhost:9200' })
+
+// promise API
+const result = await client.search({
+  index: 'my-index',
+  body: { foo: 'bar' }
+})
+
+// callback API
+client.search({
+  index: 'my-index',
+  body: { foo: 'bar' }
+}, (err, result) => {
+  if (err) console.log(err)
+})
+----
diff --git a/docs/reference.asciidoc b/docs/reference.asciidoc
diff --git a/docs/typescript.asciidoc b/docs/typescript.asciidoc
diff --git a/docs/usage.asciidoc b/docs/usage.asciidoc
diff --git a/scripts/utils/generateDocs.js b/scripts/utils/generateDocs.js

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-= Breaking changes coming from the old client`
	`1`	`+== Breaking changes coming from the old client`
`2`	`2`
`3`	`3`	If you were already using the previous version of this client --i.e. the one you used to install with `npm install elasticsearch`-- you will encounter some breaking changes.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-= Creating a child client`
	`1`	`+== Creating a child client`
`2`	`2`
`3`	`3`	There are some use cases where you may need multiple instances of the client. You can easily do that by calling `new Client()` as many times as you need, but you will lose all the benefits of using one single client, such as the long living connections and the connection pool handling. +
`4`	`4`	To avoid this problem the client offers a `child` API, which returns a new client instance that shares the connection pool with the parent client. +
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+[[as_stream_examples]]`
`1`	`2`	`== asStream`
`2`	`3`
`3`	`4`	`Instead of getting the parsed body back, you will get the raw Node.js stream of data.`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+[[ignore_examples]]`
`1`	`2`	`== Ignore`
`2`	`3`	`HTTP status codes which should not be considered errors for this request.`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-= Extend the client`
	`1`	`+== Extend the client`
`2`	`2`
`3`	`3`	`Sometimes you need to reuse the same logic, or you want to build a custom API to allow you simplify your code. +`
`4`	`4`	`The easiest way to achieve that is by extending the client.`