another batch of review updates

Author: miguelgrinberg

docs/api.rst

@@ -4,77 +4,47 @@ API Documentation
 =================
 
 Below please find the documentation for the public classes and functions of ``elasticsearch_dsl``.
+The :ref:`Asynchronous API <async_api>` classes are documented separately.
 
 .. py:module:: elasticsearch_dsl
 
 Search
 ------
 
 .. autoclass:: Search
-   :inherited-members:
    :members:
 
 .. autoclass:: MultiSearch
-   :inherited-members:
-   :members:
-
-.. autoclass:: AsyncSearch
-   :inherited-members:
-   :members:
-
-.. autoclass:: AsyncMultiSearch
-   :inherited-members:
    :members:
 
 Document
 --------
 
 .. autoclass:: Document
-   :inherited-members:
-   :members:
-
-.. autoclass:: AsyncDocument
-   :inherited-members:
    :members:
 
 Index
 -----
 
 .. autoclass:: Index
-   :inherited-members:
-   :members:
-
-.. autoclass:: AsyncIndex
-   :inherited-members:
    :members:
 
 Faceted Search
 --------------
 
 .. autoclass:: FacetedSearch
-   :inherited-members:
-   :members:
-
-.. autoclass:: AsyncFacetedSearch
-   :inherited-members:
    :members:
 
 Update By Query 
 ----------------
-
 .. autoclass:: UpdateByQuery
-   :inherited-members:
-   :members:
-
-.. autoclass:: AsyncUpdateByQuery
-   :inherited-members:
-   :members:
+  :members:
 
 Mappings
 --------
 
-If you wish to create mappings manually you can use the ``Mapping`` or ``AsyncMapping``
-classes, for more advanced use cases, however, we recommend you use the :ref:`doc_type`
+If you wish to create mappings manually you can use the ``Mapping`` class, for
+more advanced use cases, however, we recommend you use the :ref:`doc_type`
 abstraction in combination with :ref:`index` (or :ref:`index-template`) to define
 index-level settings and properties. The mapping definition follows a similar
 pattern to the query dsl:
@@ -139,5 +109,3 @@ Common field options:
 
 ``required``
   Indicates if a field requires a value for the document to be valid.
-
-

docs/async_api.rst

@@ -0,0 +1,48 @@
+.. _async_api:
+
+Asynchronous API 
+================
+
+Below please find the documentation for the asychronous classes of ``elasticsearch_dsl``.
+
+.. py:module:: elasticsearch_dsl
+   :no-index:
+
+Search
+------
+
+.. autoclass:: AsyncSearch
+   :inherited-members:
+   :members:
+
+.. autoclass:: AsyncMultiSearch
+   :inherited-members:
+   :members:
+
+Document
+--------
+
+.. autoclass:: AsyncDocument
+   :inherited-members:
+   :members:
+
+Index
+-----
+
+.. autoclass:: AsyncIndex
+   :inherited-members:
+   :members:
+
+Faceted Search
+--------------
+
+.. autoclass:: AsyncFacetedSearch
+   :inherited-members:
+   :members:
+
+Update By Query 
+----------------
+
+.. autoclass:: AsyncUpdateByQuery
+   :inherited-members:
+   :members:

docs/asyncio.rst

@@ -1,9 +1,9 @@
 .. _asyncio:
 
-Using Asyncio with Elasticsearch DSL
+Using asyncio with Elasticsearch DSL
 ====================================
 
-The ``elasticsearch-dsl`` package supports async/await with `Asyncio <https://docs.python.org/3/library/asyncio.html>`__.
+The ``elasticsearch-dsl`` package supports async/await with `asyncio <https://docs.python.org/3/library/asyncio.html>`__.
 To ensure that you have all the required dependencies, install the ``[async]`` extra:
 
    .. code:: bash
@@ -88,5 +88,7 @@ synchronous versions, but any methods that perform I/O are defined as coroutines
 Auxiliary classes that do not perform I/O do not have asynchronous versions. The
 same classes can be used in synchronous and asynchronous applications.
 
-You can consult the :ref:`api` section for details about each specific
-method.
+When using a :ref:`custom analyzer <Analysis>` in an asynchronous application, use
+the ``async_simulate()`` method to invoke the Analyze API on it.
+
+Consult the :ref:`api` section for details about each specific method.

docs/index.rst

@@ -353,5 +353,6 @@ Contents
    update_by_query
    asyncio
    api
+   async_api
    CONTRIBUTING
    Changelog

elasticsearch_dsl/search_base.py

@@ -159,7 +159,7 @@ def index(self, *index):
         """
         Set the index for the search. If called empty it will remove all information.
 
-        Example:
+        Example::
 
             s = Search()
             s = s.index('twitter-2015.01.01', 'twitter-2015.01.02')
@@ -560,6 +560,7 @@ def rank(self, rrf=None):
         :arg rrf: Set to ``True`` or an options dictionary to set the rank method to reciprocal rank fusion (RRF).
 
         Example::
+
             s = Search()
             s = s.query('match', content='search text')
             s = s.knn(field='embedding', k=5, num_candidates=10, query_vector=vector)

tests/_async/test_search.py

@@ -50,10 +50,7 @@ async def test_iter_iterates_over_hits():
     s = AsyncSearch()
     s._response = [1, 2, 3]
 
-    r = []
-    async for hit in s:
-        r.append(hit)
-    assert [1, 2, 3] == r
+    assert [1, 2, 3] == [hit async for hit in s]
 
 
 def test_cache_isnt_cloned():

tests/_sync/test_search.py

@@ -50,10 +50,7 @@ def test_iter_iterates_over_hits():
     s = Search()
     s._response = [1, 2, 3]
 
-    r = []
-    for hit in s:
-        r.append(hit)
-    assert [1, 2, 3] == r
+    assert [1, 2, 3] == [hit for hit in s]
 
 
 def test_cache_isnt_cloned():