Reorganize documentation for MkDocs & ReadTheDocs integration

.gitignore

@@ -238,3 +238,6 @@ packed
 .paket/Paket.Restore.targets
 
 **/BenchmarkDotNet.Artifacts
+
+# Python venv for MkDocs
+.env

.readthedocs.yaml

@@ -0,0 +1,11 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml

docs/README.md

@@ -16,15 +16,14 @@ Even though is a framework, we try to stick to the ASP.NET Core model as close a
 
 The CoreLib documentation is available here:
 
- 1. [General](./general/README.md),
- 2. [Basics](./basics/README.md),
- 3. [Benchmarks](./benchmarks/README.md).
- 4. [Domain](./domain/README.md).
- 5. [Architecture decision records](./adrs/README.md).
+1. [General](./general/README.md),
+2. [Basics](./basics/README.md),
+3. [Domain](./domain/README.md).
+4. [Architecture decision records](./adrs/README.md).
 
 ## Domain Driven Design
 
 LeanCode Core Library is strongly based on concepts of Domain Driven Design. If you are not familiar with this approach to developing software, you can check these books:
 
 1. Domain-Driven Design: Tackling Complexity in the Heart of Software, Eric Evans
-2. Implementing Domain-Driven Design, Vaughn Vernon
+2. Implementing Domain-Driven Design, Vaughn Vernon

docs/adrs/2021-02-04_value_object.md

@@ -1,4 +1,4 @@
-# How to implement value objects in our domains
+# Value Objects
 
 While modelling a domain we use the concept of value objects. The issue is how to represent value objects in code, as described in DDD.
 

docs/adrs/2021-11-25_optimistic_concurrency.md

@@ -1,4 +1,4 @@
-# How to handle concurrency token columns in non–MSSQL databases
+# Optimistic Concurrency
 
 The `IOptimisticConcurrency` interface requires `DateTime DateModified` and `byte[] RowVersion` properties to be implemented by aggregate roots. However, the `byte[]` representation of `RowVersion` column is specific to Microsoft SQL Server and is not compatible with other databases, such as PostgreSQL and its convention to use `uint xmin` hidden column as a concurrency token.
 

docs/adrs/README.md

@@ -1,3 +1,6 @@
 # Architecture decision records
 
- 1. [Value objects](./2021-02-04_value_object.md),
+Here, you can find a list list of [ADRs](https://adr.github.io/) that we prepared for the CoreLibrary project. The list is non-exhaustive and resembles only some of our decisions, but serves the puprose of displaying how we approach creating ADRs.
+
+1. [Value objects](./2021-02-04_value_object.md),
+2. [Optimistic Concurrency](./2021-11-25_optimistic_concurrency.md).

docs/basics/README.md

@@ -2,6 +2,6 @@
 
 Here, we describe basic elements of CoreLib-based projects:
 
- 1. [CoreLib-based apps](./01_app.md),
- 2. [CQRS](./02_cqrs.md),
- 3. [MassTransit](./03_mass_transit_integration.md).
+ 1. [CoreLib-based apps](./app.md),
+ 2. [CQRS](./cqrs.md),
+ 3. [MassTransit](./mass_transit_integration.md).

docs/basics/01_app.md → docs/basics/app.md

@@ -1,5 +1,8 @@
 # CoreLib-based apps
 
+!!! warning "Outdated"
+    This document is slightly outdated and describes v7 version of the library. v8 revampend some of the things here.
+
 CoreLib tries to make developing ASP.NET Core-based apps easier. One of the goals is to provide common features out of the box (e.g. logging & config) and unify how the app is being composed. Here, we describe what is being done and how it affects app structure.
 
 ## Used libraries

docs/basics/02_cqrs.md → docs/basics/cqrs.md

@@ -1,5 +1,8 @@
 # CQRS
 
+!!! warning "Outdated"
+    This document is slightly outdated and describes v7 version of the library. v8 revampend some of the things here.
+
 We use CQRS in almost every project. We try to stick to it as much as possible because it allows us to easily construct our APIs (using RemoteCQRS) and makes our code maintainable. Here, we present a short description on what CQRS is and how we designed it.
 
 This is not an extensive CQRS description. :)
@@ -99,12 +102,12 @@ public class CreateDishCH : ICommandHandler<AppContext, CreateDish>
 
 As you can see, the command handler is really simple - it just converts the command into new aggregate, tracking who owns the dish (`UserId` - they are the ones that have `CreateDish` permission). That does not mean this is the only responsibility of the handlers (it's just an example), but there are some guidelines related to them:
 
-1.  Keep them simple and testable, do not try to model whole flows with a single command,
-2.  Commands should rely on aggregates to gather the data (try not to use queries inside command handlers),
-3.  Commands should modify just a single aggregate (try to `AddAsync`/`UpdateAsync`/`DeleteAsync` at most once),
-4.  If the business process requires to modify multiple aggregates, try to use events and event handlers (but don't over-engineer),
-5.  If that does not help, modify/add/delete multiple aggregates,
-6.  Do not throw exceptions from inside commands. The client will receive generic error (`500 Internal Server Error`). Do it only as a last resort.
+1. Keep them simple and testable, do not try to model whole flows with a single command,
+2. Commands should rely on aggregates to gather the data (try not to use queries inside command handlers),
+3. Commands should modify just a single aggregate (try to `AddAsync`/`UpdateAsync`/`DeleteAsync` at most once),
+4. If the business process requires to modify multiple aggregates, try to use events and event handlers (but don't over-engineer),
+5. If that does not help, modify/add/delete multiple aggregates,
+6. Do not throw exceptions from inside commands. The client will receive generic error (`500 Internal Server Error`). Do it only as a last resort.
 
 #### Validation
 
@@ -293,7 +296,7 @@ All commands, queries and operations must derive from those interfaces and so th
 
 RemoteCQRS request example:
 
-```
+```bash
 curl -X POST \
   https://api.local.lncd.pl/api/query/Full.Object.Namespace.Name.FindDishesMatchingName \
   -H 'Content-Type: application/json' \

docs/basics/03_mass_transit_integration.md → docs/basics/mass_transit_integration.md

@@ -17,9 +17,9 @@ Relay module comes with a set of filters, mainly to ensure that events raised in
 The filters are:
 
 - `CorrelationFilter` - enriches logs with message ids, correlation ids and consumer types
-- `ConsumeMessagesOnceFilter`\* - see the [inbox](#Inbox)
+- `ConsumeMessagesOnceFilter`\* - see the [inbox](#inbox)
 - `EventsPublisherFilter`\* - relays Domain Events raised further in the pipeline to the bus
-- `StoreAndPublishEventsFilter`\* - as above, additionally implements [outbox](#Outbox)
+- `StoreAndPublishEventsFilter`\* - as above, additionally implements [outbox](#outbox)
 
 CAUTION: Filters marked with \* are registered via configuration observers - they are applied after other regular filters.
 This will cause an counterintuitive filters order if do not register them as last in the pipeline.