Update docs before 8.9.0 release (#1669)

Author: pquentin

README

@@ -37,6 +37,9 @@ Compatibility
 The library is compatible with all Elasticsearch versions since ``2.x`` but you
 **have to use a matching major version**:
 
+For **Elasticsearch 8.0** and later, use the major version 8 (``8.x.y``) of the
+library.
+
 For **Elasticsearch 7.0** and later, use the major version 7 (``7.x.y``) of the
 library.
 
@@ -49,10 +52,12 @@ library.
 For **Elasticsearch 2.0** and later, use the major version 2 (``2.x.y``) of the
 library.
 
-
 The recommended way to set your requirements in your `setup.py` or
 `requirements.txt` is::
 
+    # Elasticsearch 8.x
+    elasticsearch-dsl>=8.0.0,<9.0.0
+
     # Elasticsearch 7.x
     elasticsearch-dsl>=7.0.0,<8.0.0
 
@@ -66,7 +71,7 @@ The recommended way to set your requirements in your `setup.py` or
     elasticsearch-dsl>=2.0.0,<3.0.0
 
 
-The development is happening on ``master``, older branches only get bugfix releases
+The development is happening on ``main``, older branches only get bugfix releases
 
 Search Example
 --------------
@@ -76,7 +81,7 @@ Let's have a typical search request written directly as a ``dict``:
 .. code:: python
 
     from elasticsearch import Elasticsearch
-    client = Elasticsearch()
+    client = Elasticsearch("https://localhost:9200")
 
     response = client.search(
         index="my-index",
@@ -118,7 +123,7 @@ Let's rewrite the example using the Python DSL:
     from elasticsearch import Elasticsearch
     from elasticsearch_dsl import Search
 
-    client = Elasticsearch()
+    client = Elasticsearch("https://localhost:9200")
 
     s = Search(using=client, index="my-index") \
         .filter("term", category="search") \
@@ -138,15 +143,11 @@ Let's rewrite the example using the Python DSL:
 
 As you see, the library took care of:
 
-  * creating appropriate ``Query`` objects by name (eq. "match")
-
-  * composing queries into a compound ``bool`` query
-
-  * putting the ``term`` query in a filter context of the ``bool`` query
-
-  * providing a convenient access to response data
-
-  * no curly or square brackets everywhere
+- creating appropriate ``Query`` objects by name (eq. "match")
+- composing queries into a compound ``bool`` query
+- putting the ``term`` query in a filter context of the ``bool`` query
+- providing a convenient access to response data
+- no curly or square brackets everywhere
 
 
 Persistence Example
@@ -160,7 +161,7 @@ Let's have a simple Python class representing an article in a blogging system:
     from elasticsearch_dsl import Document, Date, Integer, Keyword, Text, connections
 
     # Define a default Elasticsearch client
-    connections.create_connection(hosts=['localhost'])
+    connections.create_connection(hosts="https://localhost:9200")
 
     class Article(Document):
         title = Text(analyzer='snowball', fields={'raw': Keyword()})
@@ -200,20 +201,14 @@ Let's have a simple Python class representing an article in a blogging system:
 
 In this example you can see:
 
-  * providing a default connection
-
-  * defining fields with mapping configuration
-
-  * setting index name
-
-  * defining custom methods
-
-  * overriding the built-in ``.save()`` method to hook into the persistence
-    life cycle
-
-  * retrieving and saving the object into Elasticsearch
-
-  * accessing the underlying client for other APIs
+- providing a default connection
+- defining fields with mapping configuration
+- setting index name
+- defining custom methods
+- overriding the built-in ``.save()`` method to hook into the persistence
+  life cycle
+- retrieving and saving the object into Elasticsearch
+- accessing the underlying client for other APIs
 
 You can see more in the persistence chapter of the documentation.
 

docs/index.rst

@@ -3,7 +3,7 @@ Elasticsearch DSL
 
 Elasticsearch DSL is a high-level library whose aim is to help with writing and
 running queries against Elasticsearch. It is built on top of the official
-low-level client (``elasticsearch-py``).
+low-level client (`elasticsearch-py <https://github.com/elastic/elasticsearch-py>`_).
 
 It provides a more convenient and idiomatic way to write and manipulate
 queries. It stays close to the Elasticsearch JSON DSL, mirroring its
@@ -17,6 +17,13 @@ document data in user-defined classes.
 To use the other Elasticsearch APIs (eg. cluster health) just use the
 underlying client.
 
+Installation
+------------
+
+::
+
+  pip install elasticsearch-dsl
+
 Examples
 --------
 
@@ -30,6 +37,9 @@ Compatibility
 The library is compatible with all Elasticsearch versions since ``2.x`` but you
 **have to use a matching major version**:
 
+For **Elasticsearch 8.0** and later, use the major version 8 (``8.x.y``) of the
+library.
+
 For **Elasticsearch 7.0** and later, use the major version 7 (``7.x.y``) of the
 library.
 
@@ -45,6 +55,9 @@ library.
 The recommended way to set your requirements in your `setup.py` or
 `requirements.txt` is::
 
+    # Elasticsearch 8.x
+    elasticsearch-dsl>=8.0.0,<9.0.0
+
     # Elasticsearch 7.x
     elasticsearch-dsl>=7.0.0,<8.0.0
 
@@ -58,7 +71,7 @@ The recommended way to set your requirements in your `setup.py` or
     elasticsearch-dsl>=2.0.0,<3.0.0
 
 
-The development is happening on ``master``, older branches only get bugfix releases
+The development is happening on ``main``, older branches only get bugfix releases
 
 Search Example
 --------------
@@ -68,20 +81,16 @@ Let's have a typical search request written directly as a ``dict``:
 .. code:: python
 
     from elasticsearch import Elasticsearch
-    client = Elasticsearch()
+    client = Elasticsearch("https://localhost:9200")
 
     response = client.search(
         index="my-index",
         body={
           "query": {
-            "filtered": {
-              "query": {
-                "bool": {
-                  "must": [{"match": {"title": "python"}}],
-                  "must_not": [{"match": {"description": "beta"}}]
-                }
-              },
-              "filter": {"term": {"category": "search"}}
+            "bool": {
+              "must": [{"match": {"title": "python"}}],
+              "must_not": [{"match": {"description": "beta"}}],
+              "filter": [{"term": {"category": "search"}}]
             }
           },
           "aggs" : {
@@ -114,7 +123,7 @@ Let's rewrite the example using the Python DSL:
     from elasticsearch import Elasticsearch
     from elasticsearch_dsl import Search
 
-    client = Elasticsearch()
+    client = Elasticsearch("https://localhost:9200")
 
     s = Search(using=client, index="my-index") \
         .filter("term", category="search") \
@@ -134,15 +143,11 @@ Let's rewrite the example using the Python DSL:
 
 As you see, the library took care of:
 
-  * creating appropriate ``Query`` objects by name (eq. "match")
-
-  * composing queries into a compound ``bool`` query
-
-  * creating a ``filtered`` query since ``.filter()`` was used
-
-  * providing a convenient access to response data
-
-  * no curly or square brackets everywhere
+- creating appropriate ``Query`` objects by name (eq. "match")
+- composing queries into a compound ``bool`` query
+- putting the ``term`` query in a filter context of the ``bool`` query
+- providing a convenient access to response data
+- no curly or square brackets everywhere
 
 
 Persistence Example
@@ -153,11 +158,10 @@ Let's have a simple Python class representing an article in a blogging system:
 .. code:: python
 
     from datetime import datetime
-    from elasticsearch_dsl import Document, Date, Integer, Keyword, Text
-    from elasticsearch_dsl.connections import connections
+    from elasticsearch_dsl import Document, Date, Integer, Keyword, Text, connections
 
     # Define a default Elasticsearch client
-    connections.create_connection(hosts=['localhost'])
+    connections.create_connection(hosts="https://localhost:9200")
 
     class Article(Document):
         title = Text(analyzer='snowball', fields={'raw': Keyword()})
@@ -177,7 +181,7 @@ Let's have a simple Python class representing an article in a blogging system:
             return super(Article, self).save(** kwargs)
 
         def is_published(self):
-            return datetime.now() >= self.published_from
+            return datetime.now() > self.published_from
 
     # create the mappings in elasticsearch
     Article.init()
@@ -197,20 +201,14 @@ Let's have a simple Python class representing an article in a blogging system:
 
 In this example you can see:
 
-  * providing a :ref:`default connection`
-
-  * defining fields with mapping configuration
-
-  * setting index name
-
-  * defining custom methods
-
-  * overriding the built-in ``.save()`` method to hook into the persistence
-    life cycle
-
-  * retrieving and saving the object into Elasticsearch
-
-  * accessing the underlying client for other APIs
+- providing a default connection
+- defining fields with mapping configuration
+- setting index name
+- defining custom methods
+- overriding the built-in ``.save()`` method to hook into the persistence
+  life cycle
+- retrieving and saving the object into Elasticsearch
+- accessing the underlying client for other APIs
 
 You can see more in the :ref:`persistence` chapter.
 
@@ -284,7 +282,7 @@ Writing this as a ``dict``, we would have the following code:
         },
       )
 
-Using the DSL, we can now express this query as such: 
+Using the DSL, we can now express this query as such:
 
 .. code:: python