راهنمای نصب و راه‌اندازی¶

پیش‌نیازها¶

1. نصب uv (Python Package Manager)¶

# نصب از طریق curl
curl -LsSf https://astral.sh/uv/install.sh | sh

# یا استفاده از pip
pip install uv

# بررسی نصب
uv --version

2. نصب mkdocs¶

# ایجاد پروژه
cd /home/mahdi/Projects/ice/docs-p2p

# نصب وابستگی‌ها
uv add mkdocs mkdocs-material

# یا استفاده از pip
pip install mkdocs mkdocs-material

راه‌اندازی پروژه¶

1. ساختار پوشه¶

docs-p2p/
├── mkdocs.yml          # تنظیمات MkDocs
├── docs/               # فایل‌های Markdown
│   ├── 00-introduction/
│   ├── 01-api-basics/
│   ├── 02-domain/
│   ├── 03-api-reference/
│   ├── 04-examples/
│   ├── index.md
│   └── stylesheets/
│       └── extra.css
└── .gitignore

2. تنظیمات mkdocs.yml¶

site_name: API بازار P2P
site_description: مستندات کامل API بازار اسکناس همتا به همتا
site_author: تیم توسعه

language: fa
direction: rtl

theme:
  name: material
  language: fa
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight
  palette:
    - scheme: default
      primary: indigo
      accent: indigo

plugins:
  - search:
      lang: fa

extra_css:
  - stylesheets/extra.css

nav:
  - خانه: index.md
  - معرفی:
    - کلیات سیستم: 00-introduction/overview.md
    - بازار P2P: 00-introduction/p2p-banknote-market.md
  - مبانی API:
    - REST Maturity Level 2: 01-api-basics/rest-maturity-level-2.md
    - احراز هویت: 01-api-basics/authentication.md
    - قراردادها: 01-api-basics/conventions.md
    - صفحه‌بندی: 01-api-basics/pagination-filtering.md
    - خطاها: 01-api-basics/errors.md
  - منطق دامنه:
    - منطق بازار: 02-domain/market-logic.md
    - چرخه عمر سفارش: 02-domain/order-lifecycle.md
  - رفرنس API:
    - User API: 03-api-reference/users.md
    - Wallet API: 03-api-reference/wallets.md
    - Market Symbols: 03-api-reference/market-symbols.md
    - Market Sessions: 03-api-reference/market-sessions.md
    - Orders API: 03-api-reference/orders.md
    - Trades API: 03-api-reference/trades.md
    - Market Data: 03-api-reference/market-data.md
  - مثال‌ها:
    - نمونه‌های cURL: 04-examples/curl-snippets.md
  - متغیرها: VARIABLES.md
  - سوالات متداول: faq.md
  - راهنمای سریع: QUICKSTART.md
  - راهنمای Swagger: SWAGGER.md
  - فهرست: INDEX.md

اجرا¶

1. اجرای سرور توسعه¶

# از پوشه پروژه
cd /home/mahdi/Projects/ice/docs-p2p

# اجرا با uv
uv run mkdocs serve --dev-addr 0.0.0.0:8000

# یا اگر mkdocs نصب شده
mkdocs serve --dev-addr 0.0.0.0:8000

خروجی:

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.52s
INFO    -  [10:00:00] Serving on http://0.0.0.0:8000

2. دسترسی به مستندات¶

آدرس: http://localhost:8000
یا: http://127.0.0.1:8000
از شبکه: http://:8000

3. اجرای پروداکشن¶

# ساخت سایت
mkdocs build

# خروجی در پوشه site/

پیکربندی پیشرفته¶

1. پورت دلخواه¶

# پورت 8080
mkdocs serve --dev-addr 0.0.0.0:8080

# پورت 8000 (پیش‌فرض)
mkdocs serve --dev-addr 0.0.0.0:8000

2. بازگردانی تغییرات (Hot Reload)¶

# به صورت خودکار فعال است
# هر تغییر در فایل‌ها = رفرش خودکار

3. لاگ‌های جزئی¶

mkdocs serve --dev-addr 0.0.0.0:8000 --verbose

عیب‌یابی¶

مشکل 1: Port already in use¶

# بررسی پورت‌های در حال استفاده
lsof -i :8000

# کشتن پروسه
kill -9 <PID>

# یا استفاده از پورت دیگر
mkdocs serve --dev-addr 0.0.0.0:8080

مشکل 2: Module not found¶

# نصب مجدد
uv add mkdocs mkdocs-material

# یا
pip install mkdocs mkdocs-material

مشکل 3: خطای YAML¶

# بررسی صحت فایل mkdocs.yml
mkdocs build --dry-run

# یا
python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))"

مشکل 4: فونت کار نمی‌کند¶

# بررسی فایل extra.css
ls docs/stylesheets/extra.css

# محتوای فایل باید شامل @import برای Vazirmatn باشد

دستورات مفید¶

ساخت سایت¶

mkdocs build

تمیز کردن¶

mkdocs build --clean

بررسی لینک‌های شکسته¶

mkdocs build --strict

اجرا با uv¶

# اگر pyproject.toml دارید
uv run mkdocs serve

# یا
uvx mkdocs serve

بهترین روش‌ها¶

1. توسعه¶

# همیشه از پورت 8000 استفاده کنید
mkdocs serve --dev-addr 0.0.0.0:8000

2. تست¶

# قبل از commit
mkdocs build --clean

3. داکر (اختیاری)¶

FROM squidfunk/mkdocs-material

COPY . /docs
RUN mkdocs build

docker build -t docs-p2p .
docker run -p 8000:8000 docs-p2p

خلاصه¶

نصب: uv add mkdocs mkdocs-material
اجرا: mkdocs serve --dev-addr 0.0.0.0:8000
دسترسی: http://localhost:8000
تغییرات: ذخیره خودکار = رفرش خودکار

بعدی: مطالعه راهنمای سریع