Skip to content

Commit 4dc382a

Browse files
picandocodigopicandocodigo
committed
[DOCS] Reorganize README
1 parent 6f094cf commit 4dc382a

File tree

2 files changed

+52
-52
lines changed

2 files changed

+52
-52
lines changed

‎README.md

Lines changed: 44 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,12 @@
11
# Elasticsearch
22

3-
This repository contains Ruby integrations for [Elasticsearch](https://www.elastic.co/products/elasticsearch):
4-
5-
* a client for connecting to an Elasticsearch cluster,
6-
* a Ruby API for the Elasticsearch's REST API,
7-
* a Ruby API for the X-Pack APIs,
8-
* various extensions and utilities.
9-
10-
For integration with Ruby models and Rails applications,
11-
see the **[elasticsearch-rails](https://github.com/elasticsearch/elasticsearch-rails)** project.
12-
13-
## Compatibility
14-
15-
The Elasticsearch client is compatible with Ruby 1.9 and higher.
16-
Other libraries in this repository might require a more recent Ruby version.
17-
18-
The client's API is compatible with Elasticsearch's API versions from 0.90 till current,
19-
just use a release matching major version of Elasticsearch.
20-
21-
| Gem Version | | Elasticsearch |
22-
|:-------------:|:-:| :-----------: |
23-
| 0.90 | → | 0.90 |
24-
| 1.x | → | 1.x |
25-
| 2.x | → | 2.x |
26-
| 5.x | → | 5.x |
27-
| 6.x | → | 6.x |
28-
| 7.x | → | 7.x |
29-
| master | → | master |
30-
31-
## Installation
32-
33-
Install the `elasticsearch` package from [Rubygems](https://rubygems.org/gems/elasticsearch):
34-
35-
gem install elasticsearch
36-
37-
To use an unreleased version, either add it to your `Gemfile` for [Bundler](http://gembundler.com):
38-
39-
gem 'elasticsearch', git: 'git://github.com/elasticsearch/elasticsearch-ruby.git'
40-
41-
or install it from a source code checkout:
42-
43-
git clone https://github.com/elasticsearch/elasticsearch-ruby.git
44-
cd elasticsearch-ruby/elasticsearch
45-
bundle install
46-
rake install
47-
48-
## Usage
3+
This repository contains Ruby integrations for [Elasticsearch](https://www.elastic.co/products/elasticsearch).
494

505
The [`elasticsearch`](https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch)
516
library is a wrapper for two separate libraries:
527

538
* [`elasticsearch-transport`](https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-transport),
54-
which provides a low-level Ruby client for connecting to an [Elasticsearch](https://www.elastic.co/products/elasticsearch) cluster
9+
which provides a low-level Ruby client for connecting to an Elasticsearch cluster
5510
* [`elasticsearch-api`](https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-api),
5611
which provides a Ruby API for the Elasticsearch RESTful API
5712

@@ -73,11 +28,12 @@ client.search q: 'test'
7328
```
7429

7530
Both of these libraries are extensively documented.
76-
**Please read the [`elasticsearch-transport`](http://rubydoc.info/gems/elasticsearch-transport)
77-
and the [`elasticsearch-api`](http://rubydoc.info/gems/elasticsearch-api) documentation carefully.**
31+
**Please read the [`elasticsearch-transport`](http://rubydoc.info/gems/elasticsearch-transport) and the [`elasticsearch-api`](http://rubydoc.info/gems/elasticsearch-api) documentation carefully.**
7832

79-
_Keep in mind, that for optimal performance, you should use a HTTP library which supports persistent
80-
("keep-alive") connections, e.g. [Patron](https://github.com/toland/patron) or [Typhoeus](https://github.com/typhoeus/typhoeus)._ These libraries are not dependencies of the elasticsearch gems, so be sure to define a dependency in your own application.
33+
See also [`doc/examples`](https://github.com/elastic/elasticsearch-ruby/blob/master/docs/examples/README.md) for some practical examples.
34+
35+
**For optimal performance, you should use a HTTP library which supports persistent
36+
("keep-alive") connections, e.g. [Patron](https://github.com/toland/patron) or [Typhoeus](https://github.com/typhoeus/typhoeus).** These libraries are not dependencies of the Elasticsearch gems. Ensure you define a dependency for a HTTP library in your own application.
8137

8238
This repository contains these additional Ruby libraries:
8339

@@ -86,10 +42,46 @@ This repository contains these additional Ruby libraries:
8642
* [`elasticsearch-dsl`](https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch-dsl),
8743
which provides a Ruby API for the [Elasticsearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html),
8844
* [`elasticsearch-xpack`](https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch-xpack),
89-
which provides Ruby API for the [_X-Pack_](https://www.elastic.co/products/x-pack) APIs.
45+
which provides a Ruby API for X-Pack APIs. This API is going to be merged into `elasticsearch-api` on v8.0.
9046

9147
Please see their respective READMEs for information and documentation.
9248

49+
For integration with Ruby models and Rails applications,
50+
see the **[elasticsearch-rails](https://github.com/elasticsearch/elasticsearch-rails)** project.
51+
52+
## Compatibility
53+
54+
The Elasticsearch client is compatible with currently maintained Ruby versions. See [Ruby Maintenance Branches](https://www.ruby-lang.org/en/downloads/branches/). We don't provide support to versions which have reached their end of life.
55+
56+
The gem's version numbers follow Elasticsearch's major versions. The `master` branch is compatible with the Elasticsearch `master` branch, which is the next major version.
57+
58+
| Gem Version | | Elasticsearch |
59+
|:-------------:|:-:| :-----------: |
60+
| 0.90 | → | 0.90 |
61+
| 1.x | → | 1.x |
62+
| 2.x | → | 2.x |
63+
| 5.x | → | 5.x |
64+
| 6.x | → | 6.x |
65+
| 7.x | → | 7.x |
66+
| master | → | master |
67+
68+
## Installation
69+
70+
Install the `elasticsearch` package from [Rubygems](https://rubygems.org/gems/elasticsearch):
71+
72+
gem install elasticsearch
73+
74+
To use an unreleased version, either add it to your `Gemfile` for [Bundler](http://gembundler.com):
75+
76+
gem 'elasticsearch', git: 'git://github.com/elasticsearch/elasticsearch-ruby.git'
77+
78+
or install it from a source code checkout:
79+
80+
git clone https://github.com/elasticsearch/elasticsearch-ruby.git
81+
cd elasticsearch-ruby/elasticsearch
82+
bundle install
83+
rake install
84+
9385
## Development
9486

9587
[![Build Status](https://travis-ci.org/elastic/elasticsearch-ruby.svg?branch=master)](https://travis-ci.org/elastic/elasticsearch-ruby) [![Code Climate](https://codeclimate.com/github/elastic/elasticsearch-ruby/badges/gpa.svg)](https://codeclimate.com/github/elastic/elasticsearch-ruby)

‎examples/README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Doc Examples
2+
3+
In this directory you can find:
4+
5+
- `apm`: A practical example of integrating elasticsearch-ruby and [Elastic APM](https://www.elastic.co/apm) with the [Ruby APM Agent](https://github.com/elastic/apm-agent-ruby). See the [the README](https://github.com/elastic/elasticsearch-ruby/tree/master/docs/examples/apm/README.md#observability-example).
6+
- `guide`: Contains the generated Ruby code examples for the [Elasticsearch Reference](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html).
7+
- `percolator`: An example using a percolator in Elasticsearch version 5.x and higher.
8+
- `rabbitmq`: Example of indexing the payload of a RabbitMQ queue.

0 commit comments

Comments
 (0)