Minor docs structural improvements

proteanhq · Jul 9, 2024 · 44f5919 · 44f5919
1 parent b14f840
commit 44f5919
Show file tree

Hide file tree

Showing 14 changed files with 54 additions and 29 deletions.
diff --git a/.../guides/propagate-state/event-handlers.md → docs/guides/consume-state/event-handlers.md b/.../guides/propagate-state/event-handlers.md → docs/guides/consume-state/event-handlers.md
@@ -11,7 +11,7 @@ a simplified example of an Event Handler connected to `Inventory` aggregate
 syncing stock levels corresponding to changes in the `Order` aggregate.
 
 ```python hl_lines="26-27 44"
-{! docs_src/guides/propagate-state/001.py !}
+{! docs_src/guides/consume-state/001.py !}
 ```
 
 1. `Order` aggregate fires `OrderShipped` event on book being shipped.

diff --git a/docs/guides/consume-state/index.md b/docs/guides/consume-state/index.md
@@ -0,0 +1 @@
+# Consume State Changes
diff --git a/docs/guides/projections/views.md → docs/guides/consume-state/views.md b/docs/guides/projections/views.md → docs/guides/consume-state/views.md
@@ -13,7 +13,7 @@ domain model.
 Views are defined with the `Domain.view` decorator.
 
 ```python hl_lines="15-19"
---8<-- "guides/projections/001.py:60:66"
+--8<-- "guides/consume-state/002.py:68:74"
 ```
 
 ## Workflow
@@ -55,5 +55,5 @@ Below is a full-blown example of a view `ProductInventory` synced with the
 events.
 
 ```python hl_lines="68-74 115-127 129-136"
-{! docs_src/guides/projections/001.py !}
+{! docs_src/guides/consume-state/001.py !}
 ```
diff --git a/docs/guides/domain-behavior/raising-events.md b/docs/guides/domain-behavior/raising-events.md
@@ -4,6 +4,8 @@ An aggregate rarely exists in isolation - it's state changes often mean
 that other parts of the system of the system have to sync up. In DDD, the
 mechanism to accomplish this is through Domain Events.
 
+## Delta Events
+
 When an aggregate mutates, it also (preferably) raises one or more events
 to record the state change in time, as well as propagate it within and beyond
 the bounded context.
@@ -74,4 +76,20 @@ Out[3]:
  <OrderDiscountApplied: OrderDiscountApplied object ({'order_id': '149b5549-3903-459e-9127-731266372472', 'customer_id': '1'})>]
 
 In [4]: domain.publish(order._events)
-```
+```
+
+## Fact Events
+
+[Fact events](../domain-definition/events.md#fact-events) are automatically
+generated by Protean.
+
+The event name is of the format
+`<AggregateName>FactEvent`, and the stream name will be
+`<snakecase_aggregate_name>-<fact>-<aggregate_-_id>`.
+
+```python hl_lines="10 40 42"
+{! docs_src/guides/domain-definition/events/003.py!}
+```
+
+The fact event for `User` aggregate in the above example is `UserFactEvent`
+and the output stream is `user-fact-e97cef08-f11d-43eb-8a69-251a0828bbff`
diff --git a/docs/guides/domain-definition/events.md b/docs/guides/domain-definition/events.md
@@ -149,13 +149,8 @@ event.
 Fact events are generated automatically by the framework with the
 `fact_events=True` option in the `domain.aggregate` decorator.
 
-Fact events are automatically generated by Protean. The event name is of the
-format `<AggregateName>FactEvent`, and the stream name will be
-`<snakecase_aggregate_name>-<fact>-<aggregate_-_id>`.
-
-```python hl_lines="11 38-52"
-{! docs_src/guides/domain-definition/events/003.py!}
-```
+Read about generating fact events in the section on
+[raising events](../domain-behavior/raising-events.md#fact-events).
 
 ## Immutability
 

diff --git a/docs/guides/identity.md b/docs/guides/identity.md
@@ -121,7 +121,7 @@ Out[2]:
  'id': Auto(identifier=True)}
 ```
 
-### Composite keys
+### No Composite keys
 
 Protean does not support composite keys. A `NotSupportedError` is thrown when
 multiple identifier fields are found.
@@ -148,9 +148,12 @@ configuration of an `Auto` or `Identifier`:
 {! docs_src/guides/composing-a-domain/024.py !}
 ```
 
+1. A custom function that generates identity in the form of epoch time
+2. Arguments to `Auto` field control how the identity is generated.
+
 ```shell hl_lines="4"
 In [1]: user = User(name="John Doe")
 
 In [2]: user.to_dict()
 Out[2]: {'user_id': 1718139167980, 'name': 'John Doe'}
-```
+```
diff --git a/docs/guides/projections/index.md b/docs/guides/projections/index.md
diff --git a/docs/guides/propagate-state/index.md b/docs/guides/propagate-state/index.md
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -23,6 +23,14 @@ p a, article ul li a {
   font-weight: 600;
 }
 
+.md-content__inner p, ul li {
+  font-size: 0.9em;
+}
+
+.md-typeset code {
+  font-size: 0.80em;
+}
+
 /* Primary color and tighter space */
 .md-typeset h1, .md-typeset h2, .md-typeset h3, .md-typeset h4 {
   color: var(--md-primary-fg-color);

diff --git a/docs_src/guides/composing-a-domain/024.py b/docs_src/guides/composing-a-domain/024.py
@@ -6,15 +6,15 @@
 domain = Domain(__file__, load_toml=False)
 
 
-def gen_id():
+def gen_id():  # (1)
     return int(time.time() * 1000)
 
 
 @domain.aggregate
 class User:
     user_id = Auto(
         identifier=True,
-        identity_strategy="function",
+        identity_strategy="function",  # (2)
         identity_function=gen_id,
         identity_type="integer",
     )

diff --git a/docs_src/guides/propagate-state/001.py → docs_src/guides/consume-state/001.py b/docs_src/guides/propagate-state/001.py → docs_src/guides/consume-state/001.py
diff --git a/docs_src/guides/projections/001.py → docs_src/guides/consume-state/002.py b/docs_src/guides/projections/001.py → docs_src/guides/consume-state/002.py
diff --git a/docs_src/guides/domain-definition/events/003.py b/docs_src/guides/domain-definition/events/003.py
@@ -36,17 +36,21 @@ class Account:
     """ Output:
     {
         "_metadata": {
-            "id": "__main__.User.v1.e6bb751f-1304-4609-b1ff-b0ffad8e01ad.0.1",
-            "timestamp": "2024-06-30 19:41:15.997664+00:00",
+            "id": "user-fact-e97cef08-f11d-43eb-8a69-251a0828bbff-0.1",
+            "type": "User.UserFactEvent.v1",
+            "kind": "EVENT",
+            "stream_name": "user-fact-e97cef08-f11d-43eb-8a69-251a0828bbff",
+            "origin_stream_name": null,
+            "timestamp": "2024-07-09 17:24:41.800475+00:00",
             "version": "v1",
             "sequence_id": "0.1",
-            "payload_hash": 2404640527973230107
+            "payload_hash": -1529271686230030119
         },
         "_version": 0,
         "name": "John Doe",
         "email": "[email protected]",
         "status": null,
         "account": null,
-        "id": "e6bb751f-1304-4609-b1ff-b0ffad8e01ad"
+        "id": "e97cef08-f11d-43eb-8a69-251a0828bbff"
     }
     """
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -143,18 +143,16 @@ nav:
         - guides/change-state/index.md
         - guides/change-state/commands.md
         - guides/change-state/command-handlers.md
+      - Persisting State:
         - guides/change-state/persist-aggregates.md
         - guides/change-state/unit-of-work.md
         - guides/change-state/retrieve-aggregates.md
-      - Propagating State:
-        - guides/propagate-state/index.md
-        - guides/propagate-state/event-handlers.md
-      - Projections:
-        - guides/projections/index.md
-        - guides/projections/views.md
+      - Consuming State Changes:
+        - guides/consume-state/index.md
+        - guides/consume-state/event-handlers.md
+        - guides/consume-state/views.md
 
-    #   - guides/propagate-state/events-across-contexts.md
-    #   - guides/propagate-state/views.md
+    #   - guides/consume-state/events-across-contexts.md
     # - Application Layer:
     #   - guides/app-layer/index.md
     #   - guides/app-layer/application-services.md