[7.13] Reorganize API documentation

Author: sethmlarson

MANIFEST.in

@@ -4,7 +4,6 @@ include CONTRIBUTING.md
 include LICENSE
 include MANIFEST.in
 include README.rst
-include README
 include setup.py
 recursive-include elasticsearch* py.typed *.pyi
 recursive-include docs/sphinx *

README

@@ -0,0 +1,164 @@
+Python Elasticsearch Client
+===========================
+
+.. image:: https://img.shields.io/pypi/v/elasticsearch
+   :target: https://pypi.org/project/elasticsearch
+
+.. image:: https://pepy.tech/badge/elasticsearch
+   :target: https://pepy.tech/project/elasticsearch?versions=*
+
+.. image:: https://clients-ci.elastic.co/job/elastic+elasticsearch-py+master/badge/icon
+   :target: https://clients-ci.elastic.co/job/elastic+elasticsearch-py+master
+
+.. image:: https://readthedocs.org/projects/elasticsearch-py/badge/?version=latest&style=flat
+   :target: https://elasticsearch-py.readthedocs.io
+
+Official low-level client for Elasticsearch. Its goal is to provide common
+ground for all Elasticsearch-related code in Python; because of this it tries
+to be opinion-free and very extendable.
+
+Installation
+------------
+
+Install the ``elasticsearch`` package with `pip
+<https://pypi.org/project/elasticsearch>`_::
+
+    $ python -m pip install elasticsearch
+
+If your application uses async/await in Python you can install with
+the ``async`` extra::
+
+    $ python -m pip install elasticsearch[async]
+
+Read more about `how to use asyncio with this project <https://elasticsearch-py.readthedocs.io/en/master/async.html>`_.
+
+
+Compatibility
+-------------
+
+The library is compatible with all Elasticsearch versions since ``0.90.x`` but you
+**have to use a matching major version**:
+
+For **Elasticsearch 7.0** and later, use the major version 7 (``7.x.y``) of the
+library.
+
+For **Elasticsearch 6.0** and later, use the major version 6 (``6.x.y``) of the
+library.
+
+For **Elasticsearch 5.0** and later, use the major version 5 (``5.x.y``) of the
+library.
+
+For **Elasticsearch 2.0** and later, use the major version 2 (``2.x.y``) of the
+library, and so on.
+
+The recommended way to set your requirements in your `setup.py` or
+`requirements.txt` is::
+
+    # Elasticsearch 7.x
+    elasticsearch>=7.0.0,<8.0.0
+
+    # Elasticsearch 6.x
+    elasticsearch>=6.0.0,<7.0.0
+
+    # Elasticsearch 5.x
+    elasticsearch>=5.0.0,<6.0.0
+
+    # Elasticsearch 2.x
+    elasticsearch>=2.0.0,<3.0.0
+
+If you have a need to have multiple versions installed at the same time older
+versions are also released as ``elasticsearch2`` and ``elasticsearch5``.
+
+
+Example use
+-----------
+
+.. code-block:: python
+
+    >>> from datetime import datetime
+    >>> from elasticsearch import Elasticsearch
+
+    # by default we connect to localhost:9200
+    >>> es = Elasticsearch()
+
+    # create an index in elasticsearch, ignore status code 400 (index already exists)
+    >>> es.indices.create(index='my-index', ignore=400)
+    {'acknowledged': True, 'shards_acknowledged': True, 'index': 'my-index'}
+
+    # datetimes will be serialized
+    >>> es.index(index="my-index", id=42, body={"any": "data", "timestamp": datetime.now()})
+    {'_index': 'my-index',
+     '_type': '_doc',
+     '_id': '42',
+     '_version': 1,
+     'result': 'created',
+     '_shards': {'total': 2, 'successful': 1, 'failed': 0},
+     '_seq_no': 0,
+     '_primary_term': 1}
+
+    # but not deserialized
+    >>> es.get(index="my-index", id=42)['_source']
+    {'any': 'data', 'timestamp': '2019-05-17T17:28:10.329598'}
+
+Elastic Cloud (and SSL) use-case:
+
+.. code-block:: python
+
+    >>> from elasticsearch import Elasticsearch
+    >>> es = Elasticsearch(cloud_id="<some_long_cloud_id>", http_auth=('elastic','yourpassword'))
+    >>> es.info()
+
+Using SSL Context with a self-signed cert use-case:
+
+.. code-block:: python
+
+    >>> from elasticsearch import Elasticsearch
+    >>> from ssl import create_default_context
+
+    >>> context = create_default_context(cafile="path/to/cafile.pem")
+    >>> es = Elasticsearch("https://elasticsearch.url:port", ssl_context=context, http_auth=('elastic','yourpassword'))
+    >>> es.info()
+
+
+Features
+--------
+
+The client's features include:
+
+* translating basic Python data types to and from json (datetimes are not
+  decoded for performance reasons)
+* configurable automatic discovery of cluster nodes
+* persistent connections
+* load balancing (with pluggable selection strategy) across all available nodes
+* failed connection penalization (time based - failed connections won't be
+  retried until a timeout is reached)
+* support for ssl and http authentication
+* thread safety
+* pluggable architecture
+
+
+Elasticsearch-DSL
+-----------------
+
+For a more high level client library with more limited scope, have a look at
+`elasticsearch-dsl`_ - a more pythonic library sitting on top of
+``elasticsearch-py``.
+
+`elasticsearch-dsl`_ provides a more convenient and idiomatic way to write and manipulate
+`queries`_ by mirroring the terminology and structure of Elasticsearch JSON DSL
+while exposing the whole range of the DSL from Python
+either directly using defined classes or a queryset-like expressions.
+
+It also provides an optional `persistence layer`_ for working with documents as
+Python objects in an ORM-like fashion: defining mappings, retrieving and saving
+documents, wrapping the document data in user-defined classes.
+
+.. _elasticsearch-dsl: https://elasticsearch-dsl.readthedocs.io/
+.. _queries: https://elasticsearch-dsl.readthedocs.io/en/latest/search_dsl.html
+.. _persistence layer: https://elasticsearch-dsl.readthedocs.io/en/latest/persistence.html#doctype
+
+
+License
+-------
+
+Copyright 2021 Elasticsearch B.V. Licensed under the Apache License, Version 2.0.