Skip to content

Commit c054701

Browse files
HosseinNejatiJavaremiHosseinNejatiJavaremi
committed
docs: create installation guide and streamline prerequisites
- Introduce a new `installation.md` file detailing prerequisites, installation methods, and optional dependencies for ArchiPy. - Remove installation-related content from `index.md` to enhance clarity and focus on navigation. - Update links in the documentation to ensure seamless navigation between sections.
1 parent b6068b1 commit c054701

3 files changed

Lines changed: 117 additions & 102 deletions

File tree

‎docs/index.md‎

Lines changed: 1 addition & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -95,108 +95,9 @@ def get_user(user_id: str) -> dict:
9595
!!! tip "Full examples"
9696
See the [Tutorials](examples/index.md) section for complete, runnable examples for every adapter and helper.
9797

98-
## Prerequisites
99-
100-
Before starting, ensure you have:
101-
102-
- **Python 3.14 or higher**
103-
104-
Check your version with:
105-
106-
```bash
107-
python --version
108-
```
109-
110-
If needed, [download Python 3.14+](https://www.python.org/downloads/).
111-
112-
- **UV** (recommended package manager)
113-
114-
UV is a fast Python package installer and resolver. Install it via
115-
the [official guide](https://docs.astral.sh/uv/getting-started/installation/).
116-
117-
!!! tip "Recommended Package Manager"
118-
ArchiPy recommends **`uv`** — it is significantly faster than `pip` and provides better dependency resolution.
119-
120-
## Installation Methods
121-
122-
### Using UV
123-
124-
Add the core library:
125-
126-
```bash
127-
uv add archipy
128-
```
129-
130-
With optional dependencies:
131-
132-
```bash
133-
uv add "archipy[postgres,sqlalchemy,starrocks,redis,keycloak,minio,kafka]"
134-
```
135-
136-
### Using pip
137-
138-
Install the core library:
139-
140-
```bash
141-
pip install archipy
142-
```
143-
144-
With optional dependencies:
145-
146-
```bash
147-
pip install archipy[postgres,sqlalchemy,starrocks,redis,keycloak,minio,kafka]
148-
```
149-
150-
## Optional Dependencies
151-
152-
ArchiPy supports modular features through optional extras — install only what you need:
153-
154-
| Category | Extra | Description |
155-
|---------------|---------------------------------|---------------------------------------------------|
156-
| Database | `archipy[postgres]` | PostgreSQL adapter with SQLAlchemy integration |
157-
| Database | `archipy[aiosqlite]` | SQLite async adapter with SQLAlchemy integration |
158-
| Database | `archipy[starrocks]` | StarRocks adapter with SQLAlchemy integration |
159-
| Database | `archipy[starrocks-async]` | StarRocks async adapter |
160-
| Database | `archipy[sqlalchemy]` | SQLAlchemy core integration |
161-
| Database | `archipy[sqlalchemy-async]` | SQLAlchemy async integration |
162-
| Database | `archipy[elasticsearch]` | Elasticsearch integration |
163-
| Database | `archipy[elasticsearch-async]` | Elasticsearch async integration |
164-
| Database | `archipy[scylladb]` | ScyllaDB integration |
165-
| Service | `archipy[redis]` | Redis caching and key-value storage |
166-
| Service | `archipy[keycloak]` | Authentication and authorization services |
167-
| Service | `archipy[minio]` | S3-compatible object storage |
168-
| Service | `archipy[kafka]` | Message streaming and event processing |
169-
| Service | `archipy[temporalio]` | Temporal workflow engine |
170-
| Service | `archipy[parsian-ipg]` | Payment gateway (Parsian) |
171-
| Web | `archipy[fastapi]` | FastAPI integration with middleware and utilities |
172-
| Web | `archipy[grpc]` | gRPC integration with interceptors |
173-
| Observability | `archipy[prometheus]` | Metrics and monitoring |
174-
| Observability | `archipy[sentry]` | Error tracking and monitoring |
175-
| Observability | `archipy[elastic-apm]` | Elastic APM tracing |
176-
| Utilities | `archipy[jwt]` | JSON Web Token utilities |
177-
| Utilities | `archipy[scheduler]` | Task scheduling utilities |
178-
| Utilities | `archipy[cache]` | TTL and async caching utilities |
179-
| Utilities | `archipy[dependency-injection]` | Dependency injector support |
180-
| Testing | `archipy[fakeredis]` | In-memory Redis mock for testing |
181-
| Testing | `archipy[testcontainers]` | Testcontainers integration |
182-
| Testing | `archipy[behave]` | BDD testing framework |
183-
184-
## Troubleshooting
185-
186-
If issues arise, verify:
187-
188-
1. Python version is 3.14+
189-
2. `uv` is updated (`uv self update`)
190-
3. Build tools are available (UV handles this automatically)
191-
4. Database-specific dependencies are installed if using database adapters
192-
193-
!!! tip "IDE Integration"
194-
For the best development experience, use an IDE that supports Python type hints, such as PyCharm or VS Code with the
195-
Python extension. The project uses modern Python type hints and benefits from IDE support for type checking and
196-
autocompletion.
197-
19898
## Next Steps
19999

100+
- [Installation](installation.md) — prerequisites, install methods, and optional extras
200101
- [Concepts](concepts.md) — understand the Clean Architecture layers and design philosophy
201102
- [Tutorials](examples/index.md) — step-by-step guides for every adapter, helper, and feature
202103
- [API Reference](api_reference/index.md) — full reference for all public classes and functions

‎docs/installation.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: Installation
3+
description: Prerequisites, installation methods, and optional extras for ArchiPy.
4+
---
5+
6+
# Installation
7+
8+
## Prerequisites
9+
10+
Before starting, ensure you have:
11+
12+
- **Python 3.14 or higher**
13+
14+
Check your version with:
15+
16+
```bash
17+
python --version
18+
```
19+
20+
If needed, [download Python 3.14+](https://www.python.org/downloads/).
21+
22+
- **uv** (recommended package manager)
23+
24+
uv is a fast Python package installer and resolver. Install it via
25+
the [official guide](https://docs.astral.sh/uv/getting-started/installation/).
26+
27+
!!! tip "Recommended Package Manager"
28+
ArchiPy recommends **`uv`** — it is significantly faster than `pip` and provides better dependency resolution.
29+
30+
## Install ArchiPy
31+
32+
Install the core library:
33+
34+
=== "uv"
35+
36+
```bash
37+
uv add archipy
38+
```
39+
40+
=== "pip"
41+
42+
```bash
43+
pip install archipy
44+
```
45+
46+
With optional extras (install only what you need):
47+
48+
=== "uv"
49+
50+
```bash
51+
uv add "archipy[postgres,sqlalchemy,starrocks,redis,keycloak,minio,kafka]"
52+
```
53+
54+
=== "pip"
55+
56+
```bash
57+
pip install "archipy[postgres,sqlalchemy,starrocks,redis,keycloak,minio,kafka]"
58+
```
59+
60+
## Optional Dependencies
61+
62+
ArchiPy supports modular features through optional extras — install only what you need:
63+
64+
| Category | Extra | Description |
65+
|---------------|---------------------------------|---------------------------------------------------|
66+
| Database | `archipy[postgres]` | PostgreSQL adapter with SQLAlchemy integration |
67+
| Database | `archipy[aiosqlite]` | SQLite async adapter with SQLAlchemy integration |
68+
| Database | `archipy[starrocks]` | StarRocks adapter with SQLAlchemy integration |
69+
| Database | `archipy[starrocks-async]` | StarRocks async adapter |
70+
| Database | `archipy[sqlalchemy]` | SQLAlchemy core integration |
71+
| Database | `archipy[sqlalchemy-async]` | SQLAlchemy async integration |
72+
| Database | `archipy[elasticsearch]` | Elasticsearch integration |
73+
| Database | `archipy[elasticsearch-async]` | Elasticsearch async integration |
74+
| Database | `archipy[scylladb]` | ScyllaDB integration |
75+
| Service | `archipy[redis]` | Redis caching and key-value storage |
76+
| Service | `archipy[keycloak]` | Authentication and authorization services |
77+
| Service | `archipy[minio]` | S3-compatible object storage |
78+
| Service | `archipy[kafka]` | Message streaming and event processing |
79+
| Service | `archipy[temporalio]` | Temporal workflow engine |
80+
| Service | `archipy[parsian-ipg]` | Payment gateway (Parsian) |
81+
| Web | `archipy[fastapi]` | FastAPI integration with middleware and utilities |
82+
| Web | `archipy[grpc]` | gRPC integration with interceptors |
83+
| Observability | `archipy[prometheus]` | Metrics and monitoring |
84+
| Observability | `archipy[sentry]` | Error tracking and monitoring |
85+
| Observability | `archipy[elastic-apm]` | Elastic APM tracing |
86+
| Utilities | `archipy[jwt]` | JSON Web Token utilities |
87+
| Utilities | `archipy[scheduler]` | Task scheduling utilities |
88+
| Utilities | `archipy[cache]` | TTL and async caching utilities |
89+
| Utilities | `archipy[dependency-injection]` | Dependency injector support |
90+
| Testing | `archipy[fakeredis]` | In-memory Redis mock for testing |
91+
| Testing | `archipy[testcontainers]` | Testcontainers integration |
92+
| Testing | `archipy[behave]` | BDD testing framework |
93+
94+
## Troubleshooting
95+
96+
If issues arise, verify:
97+
98+
1. Python version is 3.14+
99+
2. `uv` is updated (`uv self update`)
100+
3. Build tools are available (UV handles this automatically)
101+
4. Database-specific dependencies are installed if using database adapters
102+
103+
!!! tip "IDE Integration"
104+
For the best development experience, use an IDE that supports Python type hints, such as PyCharm or VS Code with the
105+
Python extension. The project uses modern Python type hints and benefits from IDE support for type checking and
106+
autocompletion.
107+
108+
## See Also
109+
110+
- [Get Started](index.md) — overview of ArchiPy and a quick example
111+
- [Concepts](concepts.md) — Clean Architecture layers and design philosophy
112+
- [Tutorials](examples/index.md) — complete guides for every adapter and helper

‎docs/mkdocs.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -120,8 +120,10 @@ plugins:
120120

121121
# Navigation
122122
nav:
123-
- Get Started: index.md
124-
- Concepts: concepts.md
123+
- Get Started:
124+
- Overview: index.md
125+
- Installation: installation.md
126+
- Concepts: concepts.md
125127
- Tutorials:
126128
- Overview: examples/index.md
127129
- Adapters:

0 commit comments

Comments
 (0)