Skip to content

Commit 95ce6ea

Browse files
HosseinNejatiJavaremiHosseinNejatiJavaremi
committed
docs: consolidate and restructure documentation layout
- Merge `installation.md` and `index.md` into a new `get_started.md` page - Rename `architecture.md` to `concepts.md` - Merge `contributing-docs.md` into `contributing.md` - Refresh all API reference pages (adapters, helpers, models, configs) - Update nav structure in `mkdocs.yml`, `mkdocs-fast.yml`, and `mkdocs-full.yml` - Revise and expand code examples across adapters and helpers sections
1 parent 4d540fa commit 95ce6ea

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+953
-833
lines changed

‎docs/api_reference/adapters/base.md‎

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -5,49 +5,51 @@ description: API reference for the base SQLAlchemy adapter ports, session manage
55

66
# Base SQLAlchemy
77

8-
The `base/sqlalchemy` subpackage provides the foundational SQLAlchemy components shared across all relational database adapters, including the abstract port interface, session managers, and session manager registries.
8+
The `base/sqlalchemy` subpackage provides the foundational SQLAlchemy components shared across all relational database
9+
adapters, including the abstract port interface, session managers, and session manager registries.
910

1011
## Ports
1112

1213
Abstract port interface defining the contract all SQLAlchemy-based adapters must fulfil.
1314

1415
::: archipy.adapters.base.sqlalchemy.ports
15-
options:
16-
show_root_toc_entry: false
17-
heading_level: 3
16+
options:
17+
show_root_toc_entry: false
18+
heading_level: 3
1819

1920
## Session Manager Ports
2021

2122
Abstract interface for SQLAlchemy session managers, decoupling session lifecycle from adapter logic.
2223

2324
::: archipy.adapters.base.sqlalchemy.session_manager_ports
24-
options:
25-
show_root_toc_entry: false
26-
heading_level: 3
25+
options:
26+
show_root_toc_entry: false
27+
heading_level: 3
2728

2829
## Session Manager Registry
2930

3031
Registry for tracking and resolving active session manager instances.
3132

3233
::: archipy.adapters.base.sqlalchemy.session_manager_registry
33-
options:
34-
show_root_toc_entry: false
35-
heading_level: 3
34+
options:
35+
show_root_toc_entry: false
36+
heading_level: 3
3637

3738
## Session Managers
3839

3940
Concrete session manager implementations that handle SQLAlchemy session creation, scoping, and teardown.
4041

4142
::: archipy.adapters.base.sqlalchemy.session_managers
42-
options:
43-
show_root_toc_entry: false
44-
heading_level: 3
43+
options:
44+
show_root_toc_entry: false
45+
heading_level: 3
4546

4647
## Adapters
4748

48-
The base SQLAlchemy adapter implements generic CRUD operations that concrete database adapters (PostgreSQL, SQLite, StarRocks) inherit from.
49+
The base SQLAlchemy adapter implements generic CRUD operations that concrete database adapters (PostgreSQL, SQLite,
50+
StarRocks) inherit from.
4951

5052
::: archipy.adapters.base.sqlalchemy.adapters
51-
options:
52-
show_root_toc_entry: false
53-
heading_level: 3
53+
options:
54+
show_root_toc_entry: false
55+
heading_level: 3

‎docs/api_reference/adapters/elasticsearch.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,22 +5,23 @@ description: API reference for the Elasticsearch adapter ports, adapters, and mo
55

66
# Elasticsearch
77

8-
The `elasticsearch` adapter provides integration with Elasticsearch for full-text search, document indexing, and analytics queries.
8+
The `elasticsearch` adapter provides integration with Elasticsearch for full-text search, document indexing, and
9+
analytics queries.
910

1011
## Ports
1112

1213
Abstract port interface defining the Elasticsearch adapter contract.
1314

1415
::: archipy.adapters.elasticsearch.ports
15-
options:
16-
show_root_toc_entry: false
17-
heading_level: 3
16+
options:
17+
show_root_toc_entry: false
18+
heading_level: 3
1819

1920
## Adapters
2021

2122
Concrete Elasticsearch adapter implementing index management, document CRUD, and search operations.
2223

2324
::: archipy.adapters.elasticsearch.adapters
24-
options:
25-
show_root_toc_entry: false
26-
heading_level: 3
25+
options:
26+
show_root_toc_entry: false
27+
heading_level: 3

‎docs/api_reference/adapters/email.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,15 @@ The `email` adapter provides integration with email services for sending transac
1212
Abstract port interface defining the email adapter contract.
1313

1414
::: archipy.adapters.email.ports
15-
options:
16-
show_root_toc_entry: false
17-
heading_level: 3
15+
options:
16+
show_root_toc_entry: false
17+
heading_level: 3
1818

1919
## Adapters
2020

2121
Concrete email adapter implementing SMTP-based email sending with ArchiPy conventions.
2222

2323
::: archipy.adapters.email.adapters
24-
options:
25-
show_root_toc_entry: false
26-
heading_level: 3
24+
options:
25+
show_root_toc_entry: false
26+
heading_level: 3

‎docs/api_reference/adapters/index.md‎

Lines changed: 32 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -5,25 +5,27 @@ description: Overview of all available ArchiPy adapter integrations.
55

66
# Adapters
77

8-
The `adapters` module provides concrete implementations of external system integrations following the Ports & Adapters pattern. Each adapter directory exposes a `ports.py` (abstract interface) and an `adapters.py` (concrete implementation).
8+
The `adapters` module provides concrete implementations of external system integrations following the Ports & Adapters
9+
pattern. Each adapter directory exposes a `ports.py` (abstract interface) and an `adapters.py` (concrete
10+
implementation).
911

1012
## Submodules
1113

12-
| Adapter | Description |
13-
|---|---|
14-
| [Base SQLAlchemy](base.md) | Shared SQLAlchemy session management and base CRUD adapter |
15-
| [Redis](redis.md) | Redis cache and key-value store adapter |
16-
| [PostgreSQL](postgres.md) | PostgreSQL database adapter via SQLAlchemy |
17-
| [SQLite](sqlite.md) | SQLite database adapter via SQLAlchemy |
18-
| [StarRocks](starrocks.md) | StarRocks analytical database adapter via SQLAlchemy |
19-
| [Kafka](kafka.md) | Apache Kafka message streaming adapter |
20-
| [Keycloak](keycloak.md) | Keycloak identity and access management adapter |
21-
| [MinIO](minio.md) | MinIO object storage adapter |
22-
| [ScyllaDB](scylladb.md) | ScyllaDB/Cassandra wide-column store adapter |
23-
| [Elasticsearch](elasticsearch.md) | Elasticsearch search engine adapter |
24-
| [Temporal](temporal.md) | Temporal workflow orchestration adapter |
25-
| [Email](email.md) | Email service adapter |
26-
| [Payment Gateways](payment_gateways.md) | Internet payment gateway adapters (Parsian Shaparak) |
14+
| Adapter | Description |
15+
|-----------------------------------------|------------------------------------------------------------|
16+
| [Base SQLAlchemy](base.md) | Shared SQLAlchemy session management and base CRUD adapter |
17+
| [Redis](redis.md) | Redis cache and key-value store adapter |
18+
| [PostgreSQL](postgres.md) | PostgreSQL database adapter via SQLAlchemy |
19+
| [SQLite](sqlite.md) | SQLite database adapter via SQLAlchemy |
20+
| [StarRocks](starrocks.md) | StarRocks analytical database adapter via SQLAlchemy |
21+
| [Kafka](kafka.md) | Apache Kafka message streaming adapter |
22+
| [Keycloak](keycloak.md) | Keycloak identity and access management adapter |
23+
| [MinIO](minio.md) | MinIO object storage adapter |
24+
| [ScyllaDB](scylladb.md) | ScyllaDB/Cassandra wide-column store adapter |
25+
| [Elasticsearch](elasticsearch.md) | Elasticsearch search engine adapter |
26+
| [Temporal](temporal.md) | Temporal workflow orchestration adapter |
27+
| [Email](email.md) | Email service adapter |
28+
| [Payment Gateways](payment_gateways.md) | Internet payment gateway adapters (Parsian Shaparak) |
2729

2830
## Source Code
2931

@@ -33,18 +35,18 @@ The `adapters` module provides concrete implementations of external system integ
3335

3436
## API Stability
3537

36-
| Adapter | Status | Notes |
37-
|---|---|---|
38-
| Base SQLAlchemy | 🟢 Stable | Production-ready |
39-
| Redis | 🟢 Stable | Production-ready |
40-
| PostgreSQL | 🟢 Stable | Production-ready |
41-
| SQLite | 🟢 Stable | Production-ready |
42-
| StarRocks | 🟡 Beta | API may change |
43-
| Kafka | 🟢 Stable | Production-ready |
44-
| Keycloak | 🟢 Stable | Production-ready |
45-
| MinIO | 🟢 Stable | Production-ready |
46-
| ScyllaDB | 🟢 Stable | Production-ready |
47-
| Elasticsearch | 🟢 Stable | Production-ready |
48-
| Temporal | 🟢 Stable | Production-ready |
49-
| Email | 🟢 Stable | Production-ready |
38+
| Adapter | Status | Notes |
39+
|------------------|-----------|------------------|
40+
| Base SQLAlchemy | 🟢 Stable | Production-ready |
41+
| Redis | 🟢 Stable | Production-ready |
42+
| PostgreSQL | 🟢 Stable | Production-ready |
43+
| SQLite | 🟢 Stable | Production-ready |
44+
| StarRocks | 🟡 Beta | API may change |
45+
| Kafka | 🟢 Stable | Production-ready |
46+
| Keycloak | 🟢 Stable | Production-ready |
47+
| MinIO | 🟢 Stable | Production-ready |
48+
| ScyllaDB | 🟢 Stable | Production-ready |
49+
| Elasticsearch | 🟢 Stable | Production-ready |
50+
| Temporal | 🟢 Stable | Production-ready |
51+
| Email | 🟢 Stable | Production-ready |
5052
| Payment Gateways | 🟢 Stable | Production-ready |

‎docs/api_reference/adapters/kafka.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,22 +5,23 @@ description: API reference for the Kafka adapter ports, adapters, and mocks.
55

66
# Kafka
77

8-
The `kafka` adapter provides integration with Apache Kafka for producing and consuming messages in event-driven architectures.
8+
The `kafka` adapter provides integration with Apache Kafka for producing and consuming messages in event-driven
9+
architectures.
910

1011
## Ports
1112

1213
Abstract port interface defining the Kafka adapter contract for message production and consumption.
1314

1415
::: archipy.adapters.kafka.ports
15-
options:
16-
show_root_toc_entry: false
17-
heading_level: 3
16+
options:
17+
show_root_toc_entry: false
18+
heading_level: 3
1819

1920
## Adapters
2021

2122
Concrete Kafka adapter implementing producer and consumer patterns with ArchiPy conventions.
2223

2324
::: archipy.adapters.kafka.adapters
24-
options:
25-
show_root_toc_entry: false
26-
heading_level: 3
25+
options:
26+
show_root_toc_entry: false
27+
heading_level: 3

‎docs/api_reference/adapters/keycloak.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,22 +5,23 @@ description: API reference for the Keycloak adapter ports, adapters, and mocks.
55

66
# Keycloak
77

8-
The `keycloak` adapter provides integration with Keycloak for identity and access management, including token validation, user management, and role-based access control.
8+
The `keycloak` adapter provides integration with Keycloak for identity and access management, including token
9+
validation, user management, and role-based access control.
910

1011
## Ports
1112

1213
Abstract port interface defining the Keycloak adapter contract.
1314

1415
::: archipy.adapters.keycloak.ports
15-
options:
16-
show_root_toc_entry: false
17-
heading_level: 3
16+
options:
17+
show_root_toc_entry: false
18+
heading_level: 3
1819

1920
## Adapters
2021

2122
Concrete Keycloak adapter wrapping the Keycloak REST API for authentication and authorization operations.
2223

2324
::: archipy.adapters.keycloak.adapters
24-
options:
25-
show_root_toc_entry: false
26-
heading_level: 3
25+
options:
26+
show_root_toc_entry: false
27+
heading_level: 3

‎docs/api_reference/adapters/minio.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,22 +5,23 @@ description: API reference for the MinIO adapter ports, adapters, and mocks.
55

66
# MinIO
77

8-
The `minio` adapter provides integration with MinIO (and S3-compatible object storage) for uploading, downloading, and managing binary objects.
8+
The `minio` adapter provides integration with MinIO (and S3-compatible object storage) for uploading, downloading, and
9+
managing binary objects.
910

1011
## Ports
1112

1213
Abstract port interface defining the MinIO adapter contract for object storage operations.
1314

1415
::: archipy.adapters.minio.ports
15-
options:
16-
show_root_toc_entry: false
17-
heading_level: 3
16+
options:
17+
show_root_toc_entry: false
18+
heading_level: 3
1819

1920
## Adapters
2021

2122
Concrete MinIO adapter wrapping the MinIO Python SDK with ArchiPy conventions for object storage operations.
2223

2324
::: archipy.adapters.minio.adapters
24-
options:
25-
show_root_toc_entry: false
26-
heading_level: 3
25+
options:
26+
show_root_toc_entry: false
27+
heading_level: 3

‎docs/api_reference/adapters/payment_gateways.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ description: API reference for the internet payment gateway adapters including P
55

66
# Payment Gateways
77

8-
The `internet_payment_gateways` adapter provides integration with internet payment gateways. Currently supports Parsian Shaparak, an Iranian payment gateway.
8+
The `internet_payment_gateways` adapter provides integration with internet payment gateways. Currently supports Parsian
9+
Shaparak, an Iranian payment gateway.
910

1011
## Parsian Shaparak
1112

@@ -14,6 +15,6 @@ The `internet_payment_gateways` adapter provides integration with internet payme
1415
Concrete Parsian Shaparak payment gateway adapter implementing payment initiation, verification, and reversal.
1516

1617
::: archipy.adapters.internet_payment_gateways.ir.parsian.adapters
17-
options:
18-
show_root_toc_entry: false
19-
heading_level: 3
18+
options:
19+
show_root_toc_entry: false
20+
heading_level: 3

‎docs/api_reference/adapters/postgres.md‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,31 +5,32 @@ description: API reference for the PostgreSQL adapter session managers and adapt
55

66
# PostgreSQL
77

8-
The `postgres/sqlalchemy` adapter provides a PostgreSQL-specific SQLAlchemy integration, including a concrete adapter, session manager, and session manager registry that extend the base SQLAlchemy components.
8+
The `postgres/sqlalchemy` adapter provides a PostgreSQL-specific SQLAlchemy integration, including a concrete adapter,
9+
session manager, and session manager registry that extend the base SQLAlchemy components.
910

1011
## Session Managers
1112

1213
PostgreSQL-specific session manager handling connection pooling and lifecycle for PostgreSQL databases.
1314

1415
::: archipy.adapters.postgres.sqlalchemy.session_managers
15-
options:
16-
show_root_toc_entry: false
17-
heading_level: 3
16+
options:
17+
show_root_toc_entry: false
18+
heading_level: 3
1819

1920
## Session Manager Registry
2021

2122
Registry for PostgreSQL session manager instances.
2223

2324
::: archipy.adapters.postgres.sqlalchemy.session_manager_registry
24-
options:
25-
show_root_toc_entry: false
26-
heading_level: 3
25+
options:
26+
show_root_toc_entry: false
27+
heading_level: 3
2728

2829
## Adapters
2930

3031
Concrete PostgreSQL adapter built on top of the base SQLAlchemy adapter with PostgreSQL-specific configuration.
3132

3233
::: archipy.adapters.postgres.sqlalchemy.adapters
33-
options:
34-
show_root_toc_entry: false
35-
heading_level: 3
34+
options:
35+
show_root_toc_entry: false
36+
heading_level: 3

‎docs/api_reference/adapters/redis.md‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,31 +5,33 @@ description: API reference for the Redis adapter ports, adapters, and mocks.
55

66
# Redis
77

8-
The `redis` adapter provides a complete Redis integration including the concrete adapter, its abstract port interface, and a mock implementation for testing.
8+
The `redis` adapter provides a complete Redis integration including the concrete adapter, its abstract port interface,
9+
and a mock implementation for testing.
910

1011
## Ports
1112

1213
Abstract port interface defining the Redis adapter contract.
1314

1415
::: archipy.adapters.redis.ports
15-
options:
16-
show_root_toc_entry: false
17-
heading_level: 3
16+
options:
17+
show_root_toc_entry: false
18+
heading_level: 3
1819

1920
## Adapters
2021

21-
Concrete Redis adapter wrapping the Redis client with ArchiPy conventions for cache operations, pub/sub, and key-value management.
22+
Concrete Redis adapter wrapping the Redis client with ArchiPy conventions for cache operations, pub/sub, and key-value
23+
management.
2224

2325
::: archipy.adapters.redis.adapters
24-
options:
25-
show_root_toc_entry: false
26-
heading_level: 3
26+
options:
27+
show_root_toc_entry: false
28+
heading_level: 3
2729

2830
## Mocks
2931

3032
In-memory mock implementation of the Redis port for use in unit tests and BDD scenarios.
3133

3234
::: archipy.adapters.redis.mocks
33-
options:
34-
show_root_toc_entry: false
35-
heading_level: 3
35+
options:
36+
show_root_toc_entry: false
37+
heading_level: 3

0 commit comments

Comments
 (0)