diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png new file mode 100644 index 00000000..3ea07278 Binary files /dev/null and b/docs/assets/favicon.png differ diff --git a/docs/assets/full-logo.png b/docs/assets/full-logo.png new file mode 100644 index 00000000..d60540d7 Binary files /dev/null and b/docs/assets/full-logo.png differ diff --git a/docs/assets/logo.png b/docs/assets/logo.png new file mode 100644 index 00000000..f81f1da4 Binary files /dev/null and b/docs/assets/logo.png differ diff --git a/docs/core-concepts/whitepaper.md b/docs/core-concepts/whitepaper.md deleted file mode 100644 index 77192aa2..00000000 --- a/docs/core-concepts/whitepaper.md +++ /dev/null @@ -1,47 +0,0 @@ -# Whitepaper - -## Abstract or Executive Summary - -A brief overview of the topic covered in the whitepaper, the problem being addressed, and the key findings or conclusions. - -## Introduction - -Background information or the context of the topic -The specific problem or challenge the whitepaper addresses -Objectives of the whitepaper - -## Problem Description - -A detailed explanation of the problem or issue at hand -Data or evidence that supports the existence and severity of the problem - -## Solution - -A detailed description of the proposed solution or approach -How the solution addresses the problem -Benefits and potential outcomes of implementing the solution - -# Case Studies or Examples - -Real-life examples or case studies that demonstrate the effectiveness of the proposed solution -Data and analysis supporting the success of these examples - -## Methodology - -An explanation of the methods used to gather data and develop the whitepaper -This may include research methods, analytical techniques, and sources of data - -## Conclusion - -Summary of the key points presented in the whitepaper -Reiteration of the importance of the issue and the efficacy of the proposed solution - -## Call to Action - -Suggested actions for readers or stakeholders -This might include steps to implement the solution or contact information for further engagement - -## Appendices and References - -Supporting information that is too detailed for the main body of the document -Citations of sources and additional resources for readers who want further information diff --git a/docs/guides/compose-a-domain/index.md b/docs/guides/compose-a-domain/index.md deleted file mode 100644 index aaf29ba0..00000000 --- a/docs/guides/compose-a-domain/index.md +++ /dev/null @@ -1,79 +0,0 @@ -# Compose a Domain - -A [`Domain`](../../glossary.md#domain) in Protean represents a -[Bounded Context](../../glossary.md#bounded-context) of the application. -Because it is aware of all domain elements, the `protean.Domain` class acts as -the **Composition Root** of a domain and composes all domain elements together. -It is responsible for creating and maintaining the object graph of all the -domain elements in the Bounded Context. - -`Domain` class is the one-stop gateway to: - -- Register domain elements -- Retrieve dynamically-constructed artifacts like repositories and models -- Access injected technology components at runtime - -!!! note - A **domain** here is sometimes also referred to as the "Bounded Context", - because it is an implementation of the domain model. - -!!! info - A **Composition Root** is a unique location in the application where - modules are composed together. It's the place where we instantiate objects - and their dependencies before the actual application starts running. - -## Initialize the domain object - -Constructing the object graph is a two-step procedure. First, you initialize a -domain object at a reasonable starting point of the application. - -```py hl_lines="3" -{! docs_src/guides/composing-a-domain/001.py !} -``` - -## Parameters - -### **`root_path`** - -The mandatory `root_path` parameter is the directory containing the domain's -elements. - -Typically, this is the folder containing the file initializing the domain -object. Protean uses this path to traverse the directory structure -and [auto-discover domain elements](#auto-discover-domain-elements) when the -domain is [initialized](#initialize-the-domain). - -In the example below, the domain is defined in `my_domain.py`. Domain elements -are nested within the `src` folder, directly or in their own folders. - -```shell -my_project -├── src -│ └── my_domain.py -│ └── authentication -│ └── user_aggregate.py -│ └── account_aggregate.py -├── pyproject.toml -├── poetry.lock -``` - - -Review the guide on structuring your domain for more information. - -### **`name`** - -The constructor also accepts an optional domain name to uniquely identify the -domain in the application ecosystem. - -!!!note - When not specified, the name is initialized to the name of the module - defining the domain. Typically, this is the name of the file in which - the domain is defined, without the `.py` extension. - -### **`identity_function`** - -The function to use to generate unique identity values. - -```py hl_lines="7-9 11 14" -{! docs_src/guides/composing-a-domain/022.py !} -``` diff --git a/docs/guides/index.md b/docs/guides/index.md deleted file mode 100644 index 17a450bc..00000000 --- a/docs/guides/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Guide - -Everything you need to know about using Protean. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index f71908ad..69bed77c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,20 +1,21 @@ ---- -hide: - - toc - - navigation ---- +![Protean](./assets/full-logo.png){ width="400" } +# Pragmatic Framework for Ambitious Applications -# Protean - -Protean is a DDD and CQRS-based framework that helps you build Event-driven applications. - -[![Release](https://img.shields.io/pypi/v/protean?label=Release&style=flat-square)](https://pypi.org/project/protean/) +[![Python](https://img.shields.io/pypi/pyversions/protean?label=Python)](https://github.com/proteanhq/protean/) +[![Release](https://img.shields.io/pypi/v/protean?label=Release)](https://pypi.org/project/protean/) [![Build Status](https://github.com/proteanhq/protean/actions/workflows/ci.yml/badge.svg)](https://github.com/proteanhq/protean/actions/workflows/ci.yml) [![Coverage](https://codecov.io/gh/proteanhq/protean/graph/badge.svg?token=0sFuFdLBOx)](https://codecov.io/gh/proteanhq/protean) ## Overview -**Protean helps you build applications architected for change.** +**Protean helps you build applications architected for *change* and *growth*.** + +Protean is an open-source python framework designed to build ambitious +applications that scale and evolve with your business. + +Protean offers the tools and patterns necessary for creating sustainable, +domain-driven codebases, utilizing CQRS and Event-Sourcing to tackle complexity +in high-stakes domains. At its core, Protean adopts a Domain-Driven Design (DDD) approach to development, with support for patterns to succinctly and precisely express @@ -22,13 +23,13 @@ your domain without worrying about technology aspects. When you are ready, you can seamlessly plugin technologies like databases, message brokers, and caches, and Protean will take care of the rest. -Protean is loosely based on these three paradigms: +Protean is loosely based on three paradigms: -- ***Service-Oriented*** - Develop your application as one or more subdomains that -can run independently as Microservices -- ***Event-Driven***: - Use events to propagate changes across aggregates and +- **Service-Oriented**: Develop your application as one or more subdomains +that can run independently as Microservices +- **Event-Driven**: Use events to propagate changes across aggregates and subdomains to sync state within and across Bounded Contexts. -- ***Adapter-Based***: - A configuration-driven approach to specify technology +- **Adapter-Based**: A configuration-driven approach to specify technology adapters, with multiple adapters supported out of the box. ## Features @@ -39,31 +40,43 @@ adapters, with multiple adapters supported out of the box. --- - Prototype and rapidly iterate your domain model + Prototype and rapidly iterate your domain model with core DDD tactical + patterns. - __Technology Agnostic__ --- - Model your domain without worrying about technology choices + Model your domain without worrying about technology choice. Delay your + decisions until the last responsible moment. - __Pluggable Adapters__ --- - Use a Configuration-based approach to specify technology choices + Use a Configuration-based approach to specify your application's + infrastructure. Decouple your application from your technology. -- __Multi-domain Support__ +- __Multi-domain Codebase__ --- - Evolve and structure bounded contexts over time + Evolve and structure your application's bounded contexts over time as you + understand better. - __Event-centric Communication__ --- - Use Domain Events to sync state across Aggregates and Bounded contexts + Use Domain Events to sync state across Aggregates and Bounded contexts, + creating a loosely-coupled, highly-scalable ecosystem. + +- __100% Coverage__ + + --- + + Completely cover your domain model with tests that can run in memory or + with your chosen technlogies. diff --git a/docs/overrides/partials/languages/custom.html b/docs/overrides/partials/languages/custom.html new file mode 100644 index 00000000..7ee0213f --- /dev/null +++ b/docs/overrides/partials/languages/custom.html @@ -0,0 +1,56 @@ +{% macro t(key) %}{{ { + "language": "en", + "direction": "ltr", + "action.edit": "Edit this page", + "action.skip": "Skip to content", + "action.view": "View source of this page", + "announce.dismiss": "Don't show this again", + "blog.archive": "Archive", + "blog.categories": "Categories", + "blog.categories.in": "in", + "blog.continue": "Continue reading", + "blog.draft": "Draft", + "blog.index": "Back to index", + "blog.meta": "Metadata", + "blog.references": "Related links", + "clipboard.copy": "Copy to clipboard", + "clipboard.copied": "Copied to clipboard", + "consent.accept": "Accept", + "consent.manage": "Manage settings", + "consent.reject": "Reject", + "footer": "Footer", + "footer.next": "Next", + "footer.previous": "Previous", + "header": "Header", + "meta.comments": "Comments", + "meta.source": "Source", + "nav": "Navigation", + "readtime.one": "1 min read", + "readtime.other": "# min read", + "rss.created": "RSS feed", + "rss.updated": "RSS feed of updated content", + "search": "Search", + "search.config.lang": "en", + "search.config.pipeline": "stopWordFilter", + "search.config.separator": "[\\s\\-]+", + "search.placeholder": "Search", + "search.share": "Share", + "search.reset": "Clear", + "search.result.initializer": "Initializing search", + "search.result.placeholder": "Type to start searching", + "search.result.none": "No matching documents", + "search.result.one": "1 matching document", + "search.result.other": "# matching documents", + "search.result.more.one": "1 more on this page", + "search.result.more.other": "# more on this page", + "search.result.term.missing": "Missing", + "select.language": "Select language", + "select.version": "Select version", + "source": "Go to repository", + "source.file.contributors": "Contributors", + "source.file.date.created": "Created", + "source.file.date.updated": "Last update", + "tabs": "Tabs", + "toc": "On this page", + "top": "Back to top" + }[key] }}{% endmacro %} \ No newline at end of file diff --git a/docs/start-here.md b/docs/start-here.md index 9eced18a..94bd0ab8 100644 --- a/docs/start-here.md +++ b/docs/start-here.md @@ -1,8 +1,3 @@ ---- -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. @@ -15,7 +10,8 @@ Get to know the driving principles and core ideas that shape this framework in [ ## Building with Protean -Everything you need to know to build ambitious applications with Protean. +Everything you need to know to build ambitious applications with Protean is in +the [Guides](./guides/getting-started/installation.md) section. - Craft rich domain models that capture your business concepts and rules in [Domain Model](./guides/compose-a-domain/index.md). diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index df0251e3..b464ad81 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -73,4 +73,9 @@ p a, article ul li a { .md-tabs { background-color: var(--md-primary-bg-color-light); +} + +/* Logo Height */ +.md-header__button.md-logo img, .md-header__button.md-logo svg { + height: 2rem; } \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 4dffdc8e..dee2c807 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,6 +6,10 @@ copyright: Copyright © 2019 - 2024 Subhash Bhushan theme: name: material + custom_dir: docs/overrides + logo: assets/logo.png + favicon: assets/favicon.png + language: custom font: text: Inter code: JetBrains Mono @@ -64,11 +68,11 @@ markdown_extensions: check_paths: true base_path: docs_src nav: - - Protean: index.md - - Start Here: start-here.md - - Core Concepts: + - Protean: + - index.md + - start-here.md - core-concepts/philosophy.md - - core-concepts/whitepaper.md + - Core Concepts: - core-concepts/analysis-model.md - core-concepts/streams.md # - core-concepts/identity.md @@ -103,7 +107,6 @@ nav: # - core-concepts/event-sourcing/snapshots.md # - core-concepts/event-sourcing/projections.md - Guides: - - guides/index.md - guides/getting-started/installation.md # - guides/getting-started/quickstart.md