From 998b27a64a962a3b072678a614f6529426382199 Mon Sep 17 00:00:00 2001 From: Subhash Bhushan Date: Mon, 8 Jul 2024 14:16:26 -0700 Subject: [PATCH] Minor docs structural improvements --- .../{intro => core-concepts}/anti-patterns.md | 0 docs/core-concepts/index.md | 1 + docs/{intro => core-concepts}/philosophy.md | 0 docs/{intro => core-concepts}/whitepaper.md | 0 docs/glossary.md | 50 +++++++++---------- .../compose-a-domain/initialize-domain.md | 2 +- .../compose-a-domain/register-elements.md | 2 +- .../{compose-a-domain => }/configuration.md | 2 +- docs/guides/domain-definition/aggregates.md | 4 +- .../fields/{options.md => arguments.md} | 4 +- docs/guides/domain-definition/fields/index.md | 16 +++--- .../domain-definition/fields/simple-fields.md | 6 +-- docs/guides/getting-started/start-here.md | 3 -- .../guides/{compose-a-domain => }/identity.md | 8 +-- docs/guides/index.md | 4 +- .../{compose-a-domain => }/object-model.md | 0 docs/index.md | 1 + docs/patterns/index.md | 1 + docs/start-here.md | 33 ++++++++++++ docs_src/guides/composing-a-domain/024.py | 4 +- mkdocs.yml | 25 +++++----- 21 files changed, 100 insertions(+), 66 deletions(-) rename docs/{intro => core-concepts}/anti-patterns.md (100%) create mode 100644 docs/core-concepts/index.md rename docs/{intro => core-concepts}/philosophy.md (100%) rename docs/{intro => core-concepts}/whitepaper.md (100%) rename docs/guides/{compose-a-domain => }/configuration.md (99%) rename docs/guides/domain-definition/fields/{options.md => arguments.md} (99%) delete mode 100644 docs/guides/getting-started/start-here.md rename docs/guides/{compose-a-domain => }/identity.md (93%) rename docs/guides/{compose-a-domain => }/object-model.md (100%) create mode 100644 docs/patterns/index.md create mode 100644 docs/start-here.md diff --git a/docs/intro/anti-patterns.md b/docs/core-concepts/anti-patterns.md similarity index 100% rename from docs/intro/anti-patterns.md rename to docs/core-concepts/anti-patterns.md diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md new file mode 100644 index 00000000..1152a5ba --- /dev/null +++ b/docs/core-concepts/index.md @@ -0,0 +1 @@ +# Core Concepts \ No newline at end of file diff --git a/docs/intro/philosophy.md b/docs/core-concepts/philosophy.md similarity index 100% rename from docs/intro/philosophy.md rename to docs/core-concepts/philosophy.md diff --git a/docs/intro/whitepaper.md b/docs/core-concepts/whitepaper.md similarity index 100% rename from docs/intro/whitepaper.md rename to docs/core-concepts/whitepaper.md diff --git a/docs/glossary.md b/docs/glossary.md index 77c95505..a0492588 100644 --- 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 index da6e0290..3e945965 100644 --- 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. -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 index a6843b45..90ea19c0 100644 --- 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/docs/guides/compose-a-domain/configuration.md b/docs/guides/configuration.md similarity index 99% rename from docs/guides/compose-a-domain/configuration.md rename to docs/guides/configuration.md index 850891a9..5a2f9010 100644 --- a/docs/guides/compose-a-domain/configuration.md +++ b/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 index bf723803..8e3980f4 100644 --- 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/docs/guides/domain-definition/fields/options.md b/docs/guides/domain-definition/fields/arguments.md similarity index 99% rename from docs/guides/domain-definition/fields/options.md rename to docs/guides/domain-definition/fields/arguments.md index abf847ff..4f84d275 100644 --- a/docs/guides/domain-definition/fields/options.md +++ b/docs/guides/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 index 21231c68..6e738778 100644 --- a/docs/guides/domain-definition/fields/index.md +++ b/docs/guides/domain-definition/fields/index.md @@ -16,13 +16,13 @@ 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 @@ -30,8 +30,8 @@ you to handle various real-world scenarios effectively. 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 index 1f76a549..e740b972 100644 --- 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 deleted file mode 100644 index 65e41c18..00000000 --- a/docs/guides/getting-started/start-here.md +++ /dev/null @@ -1,3 +0,0 @@ -# Start Here - -Explain the overall structure of guides and the path to follow. \ No newline at end of file diff --git a/docs/guides/compose-a-domain/identity.md b/docs/guides/identity.md similarity index 93% rename from docs/guides/compose-a-domain/identity.md rename to docs/guides/identity.md index 7a40fe99..271f805b 100644 --- a/docs/guides/compose-a-domain/identity.md +++ b/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 index 2b277933..17a450bc 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -1,3 +1,3 @@ -# User Guide +# Guide -[Command Line Interface](cli/index.md) \ No newline at end of file +Everything you need to know about using Protean. \ No newline at end of file diff --git a/docs/guides/compose-a-domain/object-model.md b/docs/guides/object-model.md similarity index 100% rename from docs/guides/compose-a-domain/object-model.md rename to docs/guides/object-model.md diff --git a/docs/index.md b/docs/index.md index 21d8c55f..f71908ad 100644 --- 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 new file mode 100644 index 00000000..70ce0735 --- /dev/null +++ b/docs/patterns/index.md @@ -0,0 +1 @@ +# Patterns \ No newline at end of file diff --git a/docs/start-here.md b/docs/start-here.md new file mode 100644 index 00000000..852dcb55 --- /dev/null +++ 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 index 56003be6..7875d6da 100644 --- 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 index 789010a6..827d25da 100644 --- 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,6 +135,10 @@ 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 @@ -145,8 +146,6 @@ nav: - 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: