Minor docs structural improvements

proteanhq · Jul 8, 2024 · 998b27a · 998b27a
1 parent febe311
commit 998b27a
Show file tree

Hide file tree

Showing 21 changed files with 100 additions and 66 deletions.
diff --git a/docs/intro/anti-patterns.md → docs/core-concepts/anti-patterns.md b/docs/intro/anti-patterns.md → docs/core-concepts/anti-patterns.md
diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md
@@ -0,0 +1 @@
+# Core Concepts
diff --git a/docs/intro/philosophy.md → docs/core-concepts/philosophy.md b/docs/intro/philosophy.md → docs/core-concepts/philosophy.md
diff --git a/docs/intro/whitepaper.md → docs/core-concepts/whitepaper.md b/docs/intro/whitepaper.md → docs/core-concepts/whitepaper.md
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -12,77 +12,77 @@ hide:
 
 # Glossary
 
-## Aggregate
+### Aggregate
 A cluster of domain objects that can be treated as a single unit. An aggregate always has one root entity.
 
-## Application Service
+### Application Service
 A service that contains business logic and orchestrates operations across multiple aggregates or domains.
 
-## Bounded Context
+### Bounded Context
 A boundary within which a particular domain model is defined and applicable. It ensures clear separation and encapsulation of models.
 
-## Category
+### Category
 A logical grouping of related streams. It can represent a business domain or a part of it.
 
-## Command
+### Command
 An instruction to perform a specific action, often resulting in a change of state within the system.
 
-## Command Handler
+### Command Handler
 A component responsible for processing commands and invoking corresponding actions on aggregates or domain services.
 
-## Command Stream
+### Command Stream
 A sequence of commands associated with a specific context or aggregate, recorded for tracking and processing purposes.
 
-## Composition
+### Composition
 The act of assembling smaller components into a more complex structure, often used to construct aggregates or services.
 
-## CQRS
+### CQRS
 Command Query Responsibility Segregation, a design pattern that separates read and write operations to optimize performance and scalability.
 
-## Custom Repository
+### Custom Repository
 A specialized repository that provides custom methods for accessing and manipulating aggregates or entities beyond the standard CRUD operations.
 
-## DAO
+### DAO
 Data Access Object, a pattern that provides an abstract interface to some type of database or other persistence mechanism.
 
-## Domain
+### Domain
 The sphere of knowledge and activity around which the business logic of the application revolves.
 
-## Domain Service
+### Domain Service
 A service that contains domain logic not belonging to any specific entity or value object, often operating across multiple aggregates.
 
-## Entity
+### Entity
 An object that is defined primarily by its identity rather than its attributes.
 
-## Event
+### Event
 A significant change in state that is captured and recorded, typically representing a historical fact within the system.
 
-## Event Handler
+### Event Handler
 A component responsible for reacting to events, often used to trigger subsequent actions or processes.
 
-## Event Sourcing
+### Event Sourcing
 A pattern in which state changes are logged as a sequence of immutable events, enabling reconstruction of past states by replaying these events.
 
-## Event Store Pattern
+### Event Store Pattern
 A storage pattern designed to persist events and support event sourcing, providing mechanisms to append and retrieve events efficiently.
 
-## Event Stream
+### Event Stream
 A chronological sequence of events related to a specific aggregate or bounded context, used to replay and reconstruct state.
 
-## Identity
+### Identity
 A unique identifier for an entity or aggregate, ensuring its distinctness within the system.
 
-## Message
+### Message
 A piece of data sent between components, often used for communication and triggering actions in event-driven architectures.
 
-## Projection
+### Projection
 A read-only view of data that is constructed by processing one or more event streams, used to support query operations.
 
-## Repository
+### Repository
 A mechanism for encapsulating storage, retrieval, and search behavior for aggregates or entities, typically abstracting the underlying data store.
 
-## Stream
+### Stream
 A continuous flow of data or events, often used to represent a series of related messages or state changes within the system.
 
-## Value Object
+### Value Object
 An immutable object that represents a descriptive aspect of the domain with no conceptual identity, defined only by its attributes.
diff --git a/docs/guides/compose-a-domain/initialize-domain.md b/docs/guides/compose-a-domain/initialize-domain.md
@@ -49,5 +49,5 @@ In the example above, the domain activates an SQLite database repository and
 makes it available for domain elements for further use.
 
 <!-- FIXME Add link to accessing active/configured dependencies -->
-Refer to [Configuration Handling](configuration.md) to understand the different ways to configure
+Refer to [Configuration handling](../configuration.md) to understand the different ways to configure
 the domain.
diff --git a/docs/guides/compose-a-domain/register-elements.md b/docs/guides/compose-a-domain/register-elements.md
@@ -24,7 +24,7 @@ depending upon the element being registered.
 In the above example, the `User` aggregate's default stream name **`user`** is
 customized to **`account`**.
 
-Review the [object model](object-model.md) to understand
+Review the [object model](../object-model.md) to understand
 multiple ways to pass these options. Refer to each domain element's
 documentation to understand the additional options supported by that element.
 

diff --git a/.../guides/compose-a-domain/configuration.md → docs/guides/configuration.md b/.../guides/compose-a-domain/configuration.md → docs/guides/configuration.md
@@ -1,4 +1,4 @@
-# Configuratiion
+# Configuration
 
 ## Primary Configuration Attributes
 

diff --git a/docs/guides/domain-definition/aggregates.md b/docs/guides/domain-definition/aggregates.md
@@ -48,7 +48,7 @@ mandatory), and also fine-tune how it is persisted (like a database column
 name in `referenced_as`).
 
 The full list of available fields in Protean and their options is available in
-[Data Fields](../data-fields/index.md) section.
+[Data Fields](../domain-definition/fields/index.md) section.
 
 ## Initialization
 
@@ -69,7 +69,7 @@ This would output something like:
 ```
 
 You see an `id` attribute appear in the results. We discuss **identity**
-deeply in a [later](identity.md) section.
+deeply in the [identity](../identity.md) section.
 
 ## Inheritance
 

diff --git a/...uides/domain-definition/fields/options.md → ...des/domain-definition/fields/arguments.md b/...uides/domain-definition/fields/options.md → ...des/domain-definition/fields/arguments.md
@@ -1,4 +1,4 @@
-# Options
+# Common Arguments
 
 ## `description`
 
@@ -65,7 +65,7 @@ primary identifier fields.
 By default, Protean dynamically generates UUIDs as values of identifier fields
 unless explicitly provided. You can customize the type of value accepted with
 `identity-strategy` config parameter. More details are in
-[Configuration](../compose-a-domain/configuration.md) section.
+[Configuration](../../configuration.md) section.
 
 ## `default`
 

diff --git a/docs/guides/domain-definition/fields/index.md b/docs/guides/domain-definition/fields/index.md
@@ -16,22 +16,22 @@ elements. They help Protean fine-tune and customize attribute access, making
 it possible to define properties, manage attributes, and control data
 validation.
 
-## Field Options
+## Field Arguments
 
-Protean fields come with various options that enhance their functionality and
-integration with the backend systems. These include required, default, choices,
-and unique, among others, which allow for a highly customizable and robust
-domain model definition. These options provide the necessary tools for
-you to handle various real-world scenarios effectively.
+Protean fields come with various options to model real-world scenarios effectively.
+These include `required`, `default`, `choices`, and `unique`, among others, which allow for a highly customizable and robust
+domain model definition.
+
+Read more in [Arguments](./arguments.md) section.
 
 ## Types of Fields
 
 ### Simple Fields
 
 Simple fields handle basic data types like strings, integers, and dates.
 They are the building blocks for defining straightforward data attributes in
-models. Options like max_length for String or max_value and min_value for
-numeric fields like Integer and Float allow developers to specify constraints
+models. Options like `max_length` for `String` or `max_value` and `min_value` for
+numeric fields like `Integer` and `Float` allow you to specify constraints
 directly in the model's definition.
 
 ### Container Fields

diff --git a/docs/guides/domain-definition/fields/simple-fields.md b/docs/guides/domain-definition/fields/simple-fields.md
@@ -183,9 +183,9 @@ Out[3]:
 ```
 
 Identity values are UUIDs by default. You can customize this behavior with
-`identity_strategy` and `identity_type` [config attributes](../../compose-a-domain/configuration.md#domain-configuration-attributes).
+`identity_strategy` and `identity_type` [config attributes](../../configuration.md#domain-configuration-attributes).
 
-The [Identity](../identity.md) section deep dives into identities in Protean.
+The [Identity](../../identity.md) section deep dives into identities in Protean.
 
 ## Identifier
 
@@ -210,5 +210,5 @@ In [2]: user.to_dict()
 Out[2]: {'user_id': 1, 'name': 'John Doe', 'subscribed': False}
 ```
 
-Refer to [Identity](../identity.md) section for a deep dive into identities
+Refer to [Identity](../../identity.md) section for a deep dive into identities
 in Protean.
diff --git a/docs/guides/getting-started/start-here.md b/docs/guides/getting-started/start-here.md
diff --git a/docs/guides/compose-a-domain/identity.md → docs/guides/identity.md b/docs/guides/compose-a-domain/identity.md → docs/guides/identity.md
@@ -11,8 +11,8 @@ helps fulfill this goal.
 
 ## Configuration
 
-Identity options are specified at the Domain level with [configuration
-attributes](./configuration#domain-configuration-attributes). A combination of
+Identity options are specified at the Domain level with
+[configuration attributes](./configuration.md#domain-configuration-attributes). A combination of
 identity strategy and identity type work together to generate identity values.
 
 ```toml
@@ -37,7 +37,7 @@ The following strategies are supported for identity generation:
 - **uuid** - Identity is a uuid4 identifier. This is the default and preferred
 strategy.
 - **function** - A function is invoked to generate identity values, supplied
-as [`identity_function`](domain-object.md#identity_function) when constructing
+as [`identity_function`](./compose-a-domain/index.md#identity_function) when constructing
 the domain object.
 
 ### Type
@@ -141,7 +141,7 @@ NotSupportedError: {'_entity': ['Multiple identifier fields found in entity Orde
 
 ## Element-level Identity Customization
 
-The identity of a single entity element can be customized by explicit
+The identity of an aggregate or entity element can be customized by explicit
 configuration of an `Auto` or `Identifier`:
 
 ```python hl_lines="9-10 15-20"

diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -1,3 +1,3 @@
-# User Guide
+# Guide
 
-[Command Line Interface](cli/index.md)
+Everything you need to know about using Protean.
diff --git a/docs/guides/compose-a-domain/object-model.md → docs/guides/object-model.md b/docs/guides/compose-a-domain/object-model.md → docs/guides/object-model.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,7 @@
 ---
 hide:
   - toc
+  - navigation
 ---
 
 # Protean

diff --git a/docs/patterns/index.md b/docs/patterns/index.md
@@ -0,0 +1 @@
+# Patterns
diff --git a/docs/start-here.md b/docs/start-here.md
@@ -0,0 +1,33 @@
+---
+hide:
+  - navigation
+---
+
+# Start Here
+
+Welcome to Protean! Whether you're a seasoned developer or new to the framework, this guide will help you navigate the documentation and get started on the right foot.
+
+## Installation
+Ready to dive in? The first step is to get Protean up and running on your system. The [Installation guide](./guides/getting-started/installation.md) will take you through a brief tour to setup Protean locally.
+
+## Core Concepts
+Time to get acquainted with the building blocks of Protean. Get to know the driving principles and core ideas that shape this framework in [Introduction](./core-concepts/index.md). In [Building Blocks](./core-concepts/building-blocks/index.md) explore key DDD concepts like Aggregates, Repositories, Events, and more, to understand the core structures of Protean.
+
+## Building with Protean
+
+Everything you need to know to build ambitious applications with Protean.
+
+- Craft rich domain models that capture your business concepts and rules in [Domain Model](./guides/compose-a-domain/index.md).
+
+- Bridge between your domain and the outside world in the section on [Application Layer](./guides/configuration.md).
+
+- Protean is batteries included - it comes pre-packaged with adapters for many popular databases, messaging systems, and other technologies. The [Infrastructure](./adapters/index.md) section will show you how to make your application rock-solid.
+
+## Patterns
+Looking for best practices? The [Patterns](./patterns/index.md) section covers common design patterns and strategies to help you use Protean effectively. Learn from tried-and-true methods to elevate your projects.
+
+## Glossary
+Stuck on a term? There is a comprehensive [Glossary](glossary.md) to help you find clear definitions for all the concepts and jargon you'll encounter as you navigate Protean.
+
+## Community
+You're not alone on this journey. Join our [Community](./community/index.md) to connect with fellow Protean users, share experiences, and get your questions answered. Together, we can make Protean even better!
diff --git a/docs_src/guides/composing-a-domain/024.py b/docs_src/guides/composing-a-domain/024.py
@@ -6,7 +6,7 @@
 domain = Domain(__file__, load_toml=False)
 
 
-def gen_ids():
+def gen_id():
     return int(time.time() * 1000)
 
 
@@ -15,7 +15,7 @@ class User:
     user_id = Auto(
         identifier=True,
         identity_strategy="function",
-        identity_function=gen_ids,
+        identity_function=gen_id,
         identity_type="integer",
     )
     name = String(required=True)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -64,12 +64,12 @@ markdown_extensions:
       check_paths: true
       base_path: docs_src
 nav:
-  - Protean:
-    - index.md
-    - intro/philosophy.md
-    - intro/whitepaper.md
+  - Protean: index.md
+  - Start Here: start-here.md
   - Core Concepts:
-    # - core-concepts/index.md
+    - core-concepts/index.md
+    - core-concepts/philosophy.md
+    - core-concepts/whitepaper.md
     - core-concepts/analysis-model.md
     - core-concepts/streams.md
     # - core-concepts/identity.md
@@ -104,7 +104,7 @@ nav:
     #   - core-concepts/event-sourcing/snapshots.md
     #   - core-concepts/event-sourcing/projections.md
   - Guides:
-    - guides/getting-started/start-here.md
+    - guides/index.md
     - guides/getting-started/installation.md
     #  - guides/getting-started/quickstart.md
 
@@ -116,14 +116,11 @@ nav:
         - guides/compose-a-domain/activate-domain.md
         - guides/compose-a-domain/when-to-compose.md
         - guides/compose-a-domain/element-decorators.md
-        - guides/compose-a-domain/object-model.md
-        - guides/compose-a-domain/configuration.md
-        - guides/compose-a-domain/identity.md
       - Defining Concepts:
         - guides/domain-definition/index.md
         - Fields:
           - guides/domain-definition/fields/index.md
-          - guides/domain-definition/fields/options.md
+          - guides/domain-definition/fields/arguments.md
           - guides/domain-definition/fields/simple-fields.md
           - guides/domain-definition/fields/container-fields.md
           - guides/domain-definition/fields/association-fields.md
@@ -138,15 +135,17 @@ nav:
         - guides/domain-behavior/aggregate-mutation.md
         - guides/domain-behavior/raising-events.md
         - guides/domain-behavior/domain-services.md
+      - guides/object-model.md
+      - guides/identity.md
+    - App Layer:
+      - guides/configuration.md
       - Changing State:
         - guides/change-state/index.md
         - guides/change-state/commands.md
         - guides/change-state/command-handlers.md
         - guides/change-state/persist-aggregates.md
         - guides/change-state/unit-of-work.md
         - guides/change-state/retrieve-aggregates.md
-
-    - App Layer:
       - Propagating State:
         - guides/propagate-state/index.md
         - guides/propagate-state/event-handlers.md
@@ -231,6 +230,8 @@ nav:
     - Event Stores:
       - adapters/eventstore/index.md
       - adapters/eventstore/message-db.md
+  - Patterns:
+    - patterns/index.md
   - glossary.md
   # - changelog.md
   - Community: