Re-juggle documentation layout

rlubke · rlubke · commit 2bf311bfe0ba · 2023-05-04T18:28:59.000-07:00
Inline examples to help demonstrate concepts.
diff --git a/docs/aggregation.rst b/docs/aggregation.rst
@@ -6,23 +6,25 @@
 Aggregation
 ===========
 
-Coherence provides developers with the ability to process some subset of the entries in a map, resulting in an
-aggregated result. See the `documentation <https://oracle.github.io/coherence/23.03/api/java/index.html>`_ for aggregators provided by this client.
-
-Assume the same set of keys and values are present from the filtering example:
-
-.. code-block:: python
-
-    from coherence import NamedMap, Session, Filters, Aggregators
-    import asyncio
-
-        # ...
-
-        await map.aggregate(Aggregators.average("age"))
-        # 47.3
-
-        await map.aggregate(Aggregators.sum("age"))
-        # 142
-
-        await map.aggregate(Filters.greater("age", 40), Aggregators.count())
-        # 2
+Sometimes you don't need the actual data objects that are stored within the
+data grid, but the derived, calculated result based on them. This is where
+Coherence aggregation features come in handy.
+
+Aggregations can be executed against the whole data set, or they can be
+limited to a subset of the data using a query or a key set.  See the utility
+class `Aggregators <api_reference.html#aggregators>`_ for the aggregators
+supported out-of-the-box by this client.
+
+The following example demonstrates various aggregation operations against
+a `NamedMap`:
+
+.. literalinclude:: ../examples/aggregators.py
+    :language: python
+    :emphasize-lines: 47, 50, 53, 56, 60
+    :linenos:
+
+* Line 47 - Returns a list of distinct hobbies across all entries
+* Line 50 - Returns a count of all Hobbits
+* Line 53 - Returns a count of all Hobbits over age 40
+* Line 56 - Returns an average of all Hobbits under the age of 40
+* Line 60 - For each hobby, list the oldest Hobbit for that interest
diff --git a/docs/api_reference.rst b/docs/api_reference.rst
@@ -6,12 +6,85 @@
 API Reference
 =============
 
+Aggregators
+-----------
+.. autoclass:: coherence.Aggregators
+    :members:
+
+Filters
+-------
+.. autoclass:: coherence.Filters
+    :members:
+
+MapEntry
+--------
+.. autoclass:: coherence.MapEntry
+    :show-inheritance:
+    :members:
+
+MapEvent
+-----------
+.. autoclass:: coherence.event.MapEvent
+    :show-inheritance:
+    :members:
+
+MapListener
+-----------
+.. autoclass:: coherence.event.MapListener
+    :show-inheritance:
+    :members:
+
+    .. automethod:: __init__
+
+NamedCache
+----------
+.. autoclass:: coherence.NamedCache
+    :show-inheritance:
+    :members:
+
+NamedMap
+--------
+.. autoclass:: coherence.NamedMap
+    :show-inheritance:
+    :members:
+
+Options
+-------
+.. autoclass:: coherence.Options
+    :show-inheritance:
+    :members:
+
+    .. automethod:: __init__
+
+Processors
+----------
+.. autoclass:: coherence.Processors
+    :members:
+
+Session
+-------
+.. autoclass:: coherence.Session
+    :show-inheritance:
+    :members:
+
+    .. automethod:: __init__
+
+TlsOptions
+----------
+.. autoclass:: coherence.TlsOptions
+    :show-inheritance:
+    :members:
+
+    .. automethod:: __init__
+
+Modules
+-------
 .. toctree::
    :maxdepth: 3
    :titlesonly:
 
-   api_reference/client.rst
    api_reference/processor.rst
    api_reference/filter.rst
+   api_reference/event.rst
    api_reference/extractor.rst
    api_reference/aggregator.rst
diff --git a/docs/api_reference/aggregator.rst b/docs/api_reference/aggregator.rst
@@ -144,5 +144,4 @@ ReducerAggregator
 Aggregators
 -----------
 .. autoclass:: coherence.aggregator.Aggregators
-    :show-inheritance:
     :members:
diff --git a/docs/api_reference/client.rst b/docs/api_reference/client.rst
diff --git a/docs/api_reference/event.rst b/docs/api_reference/event.rst
@@ -0,0 +1,40 @@
+..
+   Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+   Licensed under the Universal Permissive License v 1.0 as shown at
+   https://oss.oracle.com/licenses/upl.
+
+====================
+coherence.event
+====================
+.. toctree::
+   :maxdepth: 4
+
+MapEvent
+--------
+.. autoclass:: coherence.event.MapEvent
+    :show-inheritance:
+    :members:
+    :noindex:
+
+MapLifecycleEvent
+-----------------
+.. autoclass:: coherence.event.MapLifecycleEvent
+    :show-inheritance:
+    :members:
+    :noindex:
+
+MapEventType
+------------
+.. autoclass:: coherence.event.MapEventType
+    :show-inheritance:
+    :members:
+    :noindex:
+
+MapListener
+-----------
+.. autoclass:: coherence.event.MapListener
+    :show-inheritance:
+    :members:
+    :noindex:
+
+    .. automethod:: __init__
diff --git a/docs/api_reference/filter.rst b/docs/api_reference/filter.rst
@@ -18,7 +18,6 @@ Filter
 Filters
 -------
 .. autoclass:: coherence.filter.Filters
-    :show-inheritance:
     :members:
 
 ExtractorFilter
diff --git a/docs/api_reference/processor.rst b/docs/api_reference/processor.rst
@@ -12,7 +12,6 @@ coherence.processor
 Processors
 ---------------
 .. autoclass:: coherence.processor.Processors
-    :show-inheritance:
     :members:
 
 EntryProcessor
diff --git a/docs/basics.rst b/docs/basics.rst
@@ -6,59 +6,17 @@
 The Basics
 ==========
 
-he map (`NamedMap`) and cache (`NamedCache`) implementations provide the same basic features as the Map provided
-by Python except for the following differences:
+`NamedMap <api_reference.html#namedmap>`_ and `NamedCache <api_reference.html#namedcache>`_ are `dict`-like structures allowing users
+to store data within a remote `Coherence <https://coherence.community/>`_ cluster.
 
-* key equality isn't restricted to reference equality
-* insertion order is not maintained
-* `set()` calls cannot be chained because of the asynchronous nature of the API
+The following is an example of using a `NamedMap` to `store`, `get`, and
+`remove` simple keys and values:
 
-.. note::
-    The only difference between `NamedCache` and `NamedMap` is that the `NamedCache` allows associating a `time-to-live` on the cache entry, while `NamedMap` does not
+.. literalinclude:: ../examples/basics.py
+    :language: python
+    :emphasize-lines: 17, 19, 21-34
+    :linenos:
 
-For the following examples, let's assume that we have a Map defined in Coherence named `Test`.
-To get access to the map from the client:
-
-.. code-block:: python
-
-    from coherence import NamedMap, Session
-    import asyncio
-
-        # create a new Session to the Coherence server
-        session: Session = Session(None)
-        # create or get a map named Test from the session
-        map: NamedMap = session.get_map("Test")
-
-Once we have a handle to our map, we can invoke the same basic operations in Python:
-
-.. code-block:: python
-
-    await map.size()
-    # returns 0
-
-    await map.put("key1", "value1")
-    await map.put("key2", "value2")
-
-    await map.size()
-    # returns 2
-
-    await map.get("key1")
-    # returns "value1"
-
-    await map.get("key2")
-    # returns "value2"
-
-    await map.contains_key("key2")
-    # returns true
-
-    await map.contains_key("key3")
-    # returns false
-
-    await map.keys()
-    # ["key1", "key2"]
-
-    await map.values()
-    # ["value1", "value2"]
-
-    await map.entries()
-    # [{key: "key1", value: "value1"}, {key: "key2", value: "value2"}]
+* Line 17 - Create a new `Session` that will connect to `localhost:1408`.  See the :doc:`Sessions <sessions>` documentation for more details.
+* Line 50 - Obtain a `NamedMap` identified by `my-map` from the Session
+* Lines 21-34 - Various CRUD operations against the NamedMap such as `get() <api_reference.html#coherence.NamedMap.get>`_, `put() <api_reference.html#coherence.NamedMap.put>`_, and `remote() <api_reference.html#coherence.NamedMap.remove>`_
diff --git a/docs/entryprocessing.rst b/docs/entryprocessing.rst
@@ -6,32 +6,26 @@
 Entry Processing
 ================
 
-An entry processor allows mutation of map entries in-place within the cluster instead of bringing the entire object
-to the client, updating, and pushing the value back.  See the `documentation <https://oracle.github.io/coherence/23.03/api/java/index.html>`_ for the processors provided by this client.
-
-Assume the same set of keys and values are present from the filtering and aggregation examples:
-
-.. code-block:: python
-
-    from coherence import NamedMap, Session, Filters, Aggregators, Processors
-    import asyncio
-
-        # ...
-
-        # targeting a specific entry
-        await map.invoke("0001", Processors.extract("age"))
-        # returns: 38
-
-        # targeting all entries
-        await map.invoke_all(Processors.extract("age"))
-        # returns: [["0001", 38], ["0002", 56], ["0003", 48]]
-
-        # incrementing a number 'in-place'
-        await map.invoke_all(Filters.greater("age", 40), Processors.increment("age", 1))
-        # returns [["0002", 57], ["0003", 49]]
-
-        # update a value 'in-place'
-        await map.invoke("0001", Processors.update("age", 100))
-        # returns true meaning the value was updated
-        await map.get("0001")
-        # the value will reflect the new age value
+Entry processors are a defining feature of Coherence and provide the ability
+to send the data modification code into the grid and execute it where
+the data is, against one or more entries.  This can not only significantly
+impact how much data needs to be moved over the wire, but it also takes care
+of cluster-wide concurrency control — each entry processor has the exclusive
+access to the entry it is processing for the duration of its execution.
+
+See the utility class `Processors <api_reference.html#processors>`_ for the
+entry processors supported out-of-the-box by this client.
+
+The following example demonstrates various entry processing operations
+against a `NamedMap`:
+
+.. literalinclude:: ../examples/processors.py
+    :language: python
+    :emphasize-lines: 37, 44, 51, 57-58, 62
+    :linenos:
+
+* Line 37 - insert a new Hobbit into the `NamedMap`
+* Line 44 - invoke an entry processor to update the age of the inserted Hobbit
+* Line 51 - insert a second Hobbit into the `NamedMap`
+* Lines 57 - 58 - Increment the ages of all Hobbits in the `NamedMap` by 10.  Store the keys of the updated Hobbits
+* Line 62 - get all of the updated Hobbits to display
diff --git a/docs/events.rst b/docs/events.rst
diff --git a/docs/querying.rst b/docs/querying.rst
diff --git a/examples/events.py b/examples/events.py
