much-data/kwork-api
2
0
Fork 0
Code Issues Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity
43a75ae09b
kwork-api/docs/GITEA_PAGES.md
root 0975b68334 feat: complete Kwork API client with 45+ endpoints 
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
2026-03-29 00:42:54 +00:00

4.8 KiB
Raw Blame History

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: Первый деплой

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 файл:

# В корне проекта (не в 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 не включаются:

# Проверить что Gitea версия >= 1.19
# Админ должен включить Pages в настройках сервера

CI/CD ошибка деплоя:

# Проверить токен
# Проверить права токена (write:repository)
# Проверить что gh-pages ветка существует

404 на странице:

# Подождать 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 (бесплатно)

# Подключить репозиторий
# Build command: uv run mkdocs build
# Publish directory: site/

2. Vercel (бесплатно)

# Аналогично Netlify
# Автоматический деплой из Git

3. Cloudflare Pages (бесплатно)

# Быстрый CDN
# Автоматический HTTPS

4. Своё сервер (nginx)

# Скопировать site/ на сервер
# Настроить nginx на /var/www/kwork-api-docs/

📞 ССЫЛКИ