documentation reorg

Author: miguelgrinberg

docs/api.rst

@@ -8,35 +8,21 @@ The :ref:`Asynchronous API <async_api>` classes are documented separately.
 
 .. py:module:: elasticsearch_dsl
 
-Search
-------
-
 .. autoclass:: Search
    :members:
 
 .. autoclass:: MultiSearch
    :members:
 
-Document
---------
-
 .. autoclass:: Document
    :members:
 
-Index
------
-
 .. autoclass:: Index
    :members:
 
-Faceted Search
---------------
-
 .. autoclass:: FacetedSearch
    :members:
 
-Update By Query 
-----------------
 .. autoclass:: UpdateByQuery
   :members:
 

docs/async_api.rst

@@ -1,16 +1,13 @@
 .. _async_api:
 
-Asynchronous API 
-================
+Asynchronous API Documentation
+==============================
 
 Below please find the documentation for the asychronous classes of ``elasticsearch_dsl``.
 
 .. py:module:: elasticsearch_dsl
    :no-index:
 
-Search
-------
-
 .. autoclass:: AsyncSearch
    :inherited-members:
    :members:
@@ -19,30 +16,18 @@ Search
    :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/howtos.rst

@@ -0,0 +1,11 @@
+How-To Guides
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   search_dsl
+   persistence
+   faceted_search
+   update_by_query
+   asyncio

docs/index.rst

@@ -6,9 +6,10 @@ running queries against Elasticsearch. It is built on top of the official
 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
-terminology and structure. It exposes the whole range of the DSL from Python
-either directly using defined classes or a queryset-like expressions.
+queries using synchronous or asynchronous Python. It stays close to the
+Elasticsearch JSON DSL, mirroring its terminology and structure. It exposes the
+whole range of the DSL from Python either directly using defined classes or a
+queryset-like expressions.
 
 It also provides an optional wrapper for working with documents as Python
 objects: defining mappings, retrieving and saving documents, wrapping the
@@ -73,256 +74,6 @@ The recommended way to set your requirements in your `setup.py` or
 
 The development is happening on ``main``, older branches only get bugfix releases
 
-Search Example
---------------
-
-Let's have a typical search request written directly as a ``dict``:
-
-.. code:: python
-
-    from elasticsearch import Elasticsearch
-    client = Elasticsearch("https://localhost:9200")
-
-    response = client.search(
-        index="my-index",
-        body={
-          "query": {
-            "bool": {
-              "must": [{"match": {"title": "python"}}],
-              "must_not": [{"match": {"description": "beta"}}],
-              "filter": [{"term": {"category": "search"}}]
-            }
-          },
-          "aggs" : {
-            "per_tag": {
-              "terms": {"field": "tags"},
-              "aggs": {
-                "max_lines": {"max": {"field": "lines"}}
-              }
-            }
-          }
-        }
-    )
-
-    for hit in response['hits']['hits']:
-        print(hit['_score'], hit['_source']['title'])
-
-    for tag in response['aggregations']['per_tag']['buckets']:
-        print(tag['key'], tag['max_lines']['value'])
-
-
-
-The problem with this approach is that it is very verbose, prone to syntax
-mistakes like incorrect nesting, hard to modify (eg. adding another filter) and
-definitely not fun to write.
-
-Let's rewrite the example using the Python DSL:
-
-.. code:: python
-
-    from elasticsearch import Elasticsearch
-    from elasticsearch_dsl import Search
-
-    client = Elasticsearch("https://localhost:9200")
-
-    s = Search(using=client, index="my-index") \
-        .filter("term", category="search") \
-        .query("match", title="python")   \
-        .exclude("match", description="beta")
-
-    s.aggs.bucket('per_tag', 'terms', field='tags') \
-        .metric('max_lines', 'max', field='lines')
-
-    response = s.execute()
-
-    for hit in response:
-        print(hit.meta.score, hit.title)
-
-    for tag in response.aggregations.per_tag.buckets:
-        print(tag.key, tag.max_lines.value)
-
-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
-
-
-Persistence Example
--------------------
-
-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, connections
-
-    # Define a default Elasticsearch client
-    connections.create_connection(hosts="https://localhost:9200")
-
-    class Article(Document):
-        title = Text(analyzer='snowball', fields={'raw': Keyword()})
-        body = Text(analyzer='snowball')
-        tags = Keyword()
-        published_from = Date()
-        lines = Integer()
-
-        class Index:
-            name = 'blog'
-            settings = {
-              "number_of_shards": 2,
-            }
-
-        def save(self, ** kwargs):
-            self.lines = len(self.body.split())
-            return super(Article, self).save(** kwargs)
-
-        def is_published(self):
-            return datetime.now() > self.published_from
-
-    # create the mappings in elasticsearch
-    Article.init()
-
-    # create and save and article
-    article = Article(meta={'id': 42}, title='Hello world!', tags=['test'])
-    article.body = ''' looong text '''
-    article.published_from = datetime.now()
-    article.save()
-
-    article = Article.get(id=42)
-    print(article.is_published())
-
-    # Display cluster health
-    print(connections.get_connection().cluster.health())
-
-
-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
-
-You can see more in the :ref:`persistence` chapter.
-
-
-Pre-built Faceted Search
-------------------------
-
-If you have your ``Document``\ s defined you can very easily create a faceted
-search class to simplify searching and filtering.
-
-.. note::
-
-    This feature is experimental and may be subject to change.
-
-.. code:: python
-
-    from elasticsearch_dsl import FacetedSearch, TermsFacet, DateHistogramFacet
-
-    class BlogSearch(FacetedSearch):
-        doc_types = [Article, ]
-        # fields that should be searched
-        fields = ['tags', 'title', 'body']
-
-        facets = {
-            # use bucket aggregations to define facets
-            'tags': TermsFacet(field='tags'),
-            'publishing_frequency': DateHistogramFacet(field='published_from', interval='month')
-        }
-
-    # empty search
-    bs = BlogSearch()
-    response = bs.execute()
-
-    for hit in response:
-        print(hit.meta.score, hit.title)
-
-    for (tag, count, selected) in response.facets.tags:
-        print(tag, ' (SELECTED):' if selected else ':', count)
-
-    for (month, count, selected) in response.facets.publishing_frequency:
-        print(month.strftime('%B %Y'), ' (SELECTED):' if selected else ':', count)
-
-You can find more details in the :ref:`faceted_search` chapter.
-
-
-Update By Query Example
-------------------------
-
-Let's resume the simple example of articles on a blog, and let's assume that each article has a number of likes.
-For this example, imagine we want to increment the number of likes by 1 for all articles that match a certain tag and do not match a certain description.
-Writing this as a ``dict``, we would have the following code:
-
-.. code:: python
-
-    from elasticsearch import Elasticsearch
-    client = Elasticsearch()
-
-    response = client.update_by_query(
-        index="my-index",
-        body={
-          "query": {
-            "bool": {
-              "must": [{"match": {"tag": "python"}}],
-              "must_not": [{"match": {"description": "beta"}}]
-            }
-          },
-          "script"={
-            "source": "ctx._source.likes++",
-            "lang": "painless"
-          }
-        },
-      )
-
-Using the DSL, we can now express this query as such:
-
-.. code:: python
-
-    from elasticsearch import Elasticsearch
-    from elasticsearch_dsl import Search, UpdateByQuery
-
-    client = Elasticsearch()
-    ubq = UpdateByQuery(using=client, index="my-index") \
-          .query("match", title="python")   \
-          .exclude("match", description="beta") \
-          .script(source="ctx._source.likes++", lang="painless")
-
-    response = ubq.execute()
-
-As you can see, the ``Update By Query`` object provides many of the savings offered
-by the ``Search`` object, and additionally allows one to update the results of the search
-based on a script assigned in the same manner.
-
-Migration from ``elasticsearch-py``
------------------------------------
-
-You don't have to port your entire application to get the benefits of the
-Python DSL, you can start gradually by creating a ``Search`` object from your
-existing ``dict``, modifying it using the API and serializing it back to a
-``dict``:
-
-.. code:: python
-
-    body = {...} # insert complicated query here
-
-    # Convert to Search object
-    s = Search.from_dict(body)
-
-    # Add some filters, aggregations, queries, ...
-    s.filter("term", tags="python")
-
-    # Convert back to dict to plug back into existing code
-    body = s.to_dict()
-
-
 License
 -------
 
@@ -346,13 +97,10 @@ Contents
 .. toctree::
    :maxdepth: 2
 
+   self
    configuration
-   search_dsl
-   persistence
-   faceted_search
-   update_by_query
-   asyncio
-   api
-   async_api
+   tutorials
+   howtos
+   reference
    CONTRIBUTING
    Changelog

docs/reference.rst

@@ -0,0 +1,8 @@
+Reference
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+   async_api