0975b68334
Initial release: - Complete async API client (45+ endpoints) - Pydantic models for all responses - Two-step authentication - Comprehensive error handling - 92% test coverage - Gitea Actions CI/CD - Semantic release configured
212 lines
4.8 KiB
Markdown
212 lines
4.8 KiB
Markdown
# Gitea Pages — Хостинг документации
|
||
|
||
## 📋 Обзор
|
||
|
||
**Gitea Pages** — аналог GitHub Pages для хостинга статических сайтов напрямую из Gitea.
|
||
|
||
**URL документации:** `https://git.much-data.ru/claw/kwork-api/`
|
||
|
||
---
|
||
|
||
## 🔧 НАСТРОЙКА
|
||
|
||
### **Шаг 1: Включить Pages в репозитории**
|
||
|
||
1. Зайди в https://git.much-data.ru/claw/kwork-api
|
||
2. **Settings** → **Pages**
|
||
3. Включить **Enable Pages**
|
||
4. Выбрать источник:
|
||
- **Source:** `gh-pages` branch
|
||
- **Folder:** `/ (root)`
|
||
5. **Save**
|
||
|
||
---
|
||
|
||
### **Шаг 2: Настроить Gitea Token**
|
||
|
||
1. https://git.much-data.ru → Settings → Applications
|
||
2. Создать токен с правами:
|
||
- `write:repository`
|
||
- `write:package`
|
||
3. Скопировать токен
|
||
4. В репозитории: **Settings** → **Secrets**
|
||
5. Добавить секрет: `GITEA_TOKEN` = твой токен
|
||
|
||
---
|
||
|
||
### **Шаг 3: Первый деплой**
|
||
|
||
```bash
|
||
cd /root/kwork-api
|
||
|
||
# Собрать документацию
|
||
uv run mkdocs build
|
||
|
||
# Проверить что site/ создан
|
||
ls -la site/
|
||
|
||
# Закоммитить и запушить
|
||
git add .
|
||
git commit -m "docs: initial documentation"
|
||
git push origin main
|
||
|
||
# CI/CD автоматически задеплоит на gh-pages
|
||
```
|
||
|
||
---
|
||
|
||
### **Шаг 4: Проверить**
|
||
|
||
После успешного CI/CD:
|
||
|
||
**Документация доступна:**
|
||
```
|
||
https://git.much-data.ru/claw/kwork-api/
|
||
```
|
||
|
||
Или если включён custom domain:
|
||
```
|
||
https://kwork-api.much-data.ru/
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 АВТОМАТИЧЕСКИЙ ДЕПЛОЙ
|
||
|
||
**Workflow срабатывает при:**
|
||
- ✅ Push в `main` ветку
|
||
- ✅ Создании тега релиза
|
||
|
||
**Что делает:**
|
||
1. Собирает MkDocs документацию
|
||
2. Пушит в `gh-pages` ветку
|
||
3. Gitea Pages автоматически обновляет сайт
|
||
|
||
---
|
||
|
||
## 🌐 CUSTOM DOMAIN (опционально)
|
||
|
||
### **DNS настройка:**
|
||
|
||
```
|
||
# В панели управления доменом much-data.ru
|
||
|
||
# CNAME запись:
|
||
kwork-api CNAME git.much-data.ru
|
||
|
||
# Или A запись:
|
||
kwork-api A 5.188.26.192
|
||
```
|
||
|
||
### **В Gitea Pages:**
|
||
|
||
1. **Settings** → **Pages**
|
||
2. **Custom Domain:** `kwork-api.much-data.ru`
|
||
3. **Save**
|
||
|
||
### **Создать CNAME файл:**
|
||
|
||
```bash
|
||
# В корне проекта (не в site/)
|
||
echo "kwork-api.much-data.ru" > static/CNAME
|
||
git add static/CNAME
|
||
git commit -m "docs: add custom domain"
|
||
git push
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 СТРУКТУРА ВЕТКИ
|
||
|
||
```
|
||
main (исходный код)
|
||
├── src/
|
||
├── docs/
|
||
├── mkdocs.yml
|
||
└── .github/workflows/ci.yml
|
||
|
||
gh-pages (автоматически, только сайт)
|
||
├── index.html
|
||
├── api-reference/
|
||
├── search/
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 TROUBLESHOOTING
|
||
|
||
### **Pages не включаются:**
|
||
|
||
```bash
|
||
# Проверить что Gitea версия >= 1.19
|
||
# Админ должен включить Pages в настройках сервера
|
||
```
|
||
|
||
### **CI/CD ошибка деплоя:**
|
||
|
||
```bash
|
||
# Проверить токен
|
||
# Проверить права токена (write:repository)
|
||
# Проверить что gh-pages ветка существует
|
||
```
|
||
|
||
### **404 на странице:**
|
||
|
||
```bash
|
||
# Подождать 1-2 минуты (Gitea обрабатывает)
|
||
# Проверить что site/ не пустой
|
||
# Проверить workflow логи
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 ЧЕКЛИСТ
|
||
|
||
- [ ] Включить Pages в настройках репозитория
|
||
- [ ] Создать Gitea Token
|
||
- [ ] Добавить токен в Secrets (`GITEA_TOKEN`)
|
||
- [ ] Запушить изменения в main
|
||
- [ ] Дождаться CI/CD
|
||
- [ ] Проверить https://git.much-data.ru/claw/kwork-api/
|
||
- [ ] (Опционально) Настроить custom domain
|
||
|
||
---
|
||
|
||
## 🎯 АЛЬТЕРНАТИВЫ
|
||
|
||
Если Gitea Pages не работает:
|
||
|
||
### **1. Netlify (бесплатно)**
|
||
```bash
|
||
# Подключить репозиторий
|
||
# Build command: uv run mkdocs build
|
||
# Publish directory: site/
|
||
```
|
||
|
||
### **2. Vercel (бесплатно)**
|
||
```bash
|
||
# Аналогично Netlify
|
||
# Автоматический деплой из Git
|
||
```
|
||
|
||
### **3. Cloudflare Pages (бесплатно)**
|
||
```bash
|
||
# Быстрый CDN
|
||
# Автоматический HTTPS
|
||
```
|
||
|
||
### **4. Своё сервер (nginx)**
|
||
```bash
|
||
# Скопировать site/ на сервер
|
||
# Настроить nginx на /var/www/kwork-api-docs/
|
||
```
|
||
|
||
---
|
||
|
||
## 📞 ССЫЛКИ
|
||
|
||
- [Gitea Pages Documentation](https://docs.gitea.com/usage/pages)
|
||
- [MkDocs Documentation](https://www.mkdocs.org/)
|
||
- [Gitea Actions](https://docs.gitea.com/usage/actions)
|