ai-docs-gen 0.1.10

CLI-инструмент для генерации технической документации по коду и конфигурациям

ai_docs — генератор технической документации

English version | Русская версия

Обзор

ai_docs — CLI‑инструмент для генерации технической документации по коду и конфигурациям. Поддерживает локальные папки, локальные git‑проекты и удалённые git‑репозитории. Генерирует README.md и MkDocs‑сайт (с автоматической сборкой).

Ключевые возможности:

• Автоопределение доменов инфраструктуры (Kubernetes, Helm, Terraform, Ansible, Docker, CI/CD, Observability, Service Mesh / Ingress, Data / Storage)
• Инкрементальная генерация и кэширование
• Учет .gitignore и фильтрация файлов
• Параллельная LLM‑суммаризация (--threads / AI_DOCS_THREADS)
• Отчёт об изменениях в docs/changes.md

Быстрый старт

1. Установка зависимостей:

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

Альтернатива (установка как пакет):

python3 -m venv .venv
. .venv/bin/activate
pip install ai-docs-gen

Локальная установка в editable‑режиме:

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

2. Настройка переменных окружения (пример — .env.example):

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=
OPENAI_MODEL=gpt-4o-mini
OPENAI_MAX_TOKENS=1200
OPENAI_CONTEXT_TOKENS=8192
OPENAI_TEMPERATURE=0.2
AI_DOCS_THREADS=1
AI_DOCS_LOCAL_SITE=false

Если инструмент установлен как пакет, можно задать переменные окружения так:

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL=""
export OPENAI_MODEL="gpt-4o-mini"
export OPENAI_MAX_TOKENS="1200"
export OPENAI_CONTEXT_TOKENS="8192"
export OPENAI_TEMPERATURE="0.2"
export AI_DOCS_THREADS="1"
export AI_DOCS_LOCAL_SITE="false"

3. Генерация README и MkDocs:

python -m ai_docs --source .

Альтернативно:

python ai_docs --source .

Если установлен как пакет:

ai-docs --source .

Примечание для Windows:

• Пути обрабатываются корректно, но внутри всегда нормализуются в формат с /.
• Если используете PowerShell, пример активации venv и переменных окружения:

python -m venv .venv
.\\.venv\\Scripts\\Activate.ps1
$env:OPENAI_API_KEY="your_api_key_here"
$env:OPENAI_BASE_URL=""
$env:OPENAI_MODEL="gpt-4o-mini"
$env:OPENAI_MAX_TOKENS="1200"
$env:OPENAI_CONTEXT_TOKENS="8192"
$env:OPENAI_TEMPERATURE="0.2"
$env:AI_DOCS_THREADS="1"
$env:AI_DOCS_LOCAL_SITE="false"

Примеры использования

Локальная папка:

python -m ai_docs --source /path/to/project

Локальный git‑проект:

python -m ai_docs --source ~/projects/my-repo

Удалённый репозиторий:

python -m ai_docs --source https://github.com/org/repo.git

Только README:

python -m ai_docs --source . --readme

Только MkDocs:

python -m ai_docs --source . --mkdocs

Локальный режим для MkDocs:

python -m ai_docs --source . --mkdocs --local-site

Интеграция в CI/CD

Пример для GitHub Actions:

- name: Generate Docs
  run: |
    pip install ai-docs-gen
    ai-docs --source . --mkdocs --readme --language en --force
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Что генерируется

• README.md — краткое описание проекта
• .ai-docs/ — страницы документации
• .ai-docs/overview.md — сохранённый обзор проекта (используется для README и MkDocs)
• .ai-docs/changes.md — изменения с последней генерации
• .ai-docs/modules/ — детальная документация модулей (страница на модуль, Doxygen‑подобное описание функций/классов/параметров)
• .ai-docs/configs/ — документация конфигов проекта (обзор + страницы конфигов в универсальном стиле)
• .ai-docs/_index.json — навигационный индекс документации (правила маршрутизации, список секций и модулей)
• mkdocs.yml — конфиг MkDocs
• ai_docs_site/ — собранный сайт MkDocs
• .ai_docs_cache/ — кэш и промежуточные summary‑файлы

Поддерживаемые языки и расширения

Поддержка основана на расширениях кода в ai_docs/domain.py: .py, .pyi, .pyx, .js, .jsx, .ts, .tsx, .go, .java, .c, .cc, .cpp, .h, .hpp, .rs, .rb, .php, .cs, .kt, .kts, .swift, .m, .mm, .vb, .bas, .sql, .pas, .dpr, .pp, .r, .pl, .pm, .f, .for, .f90, .f95, .f03, .f08, .sb3, .adb, .ads, .asm, .s, .ino, .htm, .html, .css.

Индекс документации

Файл .ai-docs/_index.json строится автоматически при генерации и содержит:

• список секций и модулей (пути и краткие описания);
• правила маршрутизации: приоритет modules/index.md → modules/* → index.md/architecture.md/conventions.md;
• принцип ранжирования: частота ключевых совпадений + приоритет файла.

.ai-docs.yaml (расширения)

Если в проекте есть файл .ai-docs.yaml, он задаёт приоритетный список расширений для сканирования. Если файла нет, он создаётся автоматически на основе текущих *_EXTENSIONS.

Формат (поддерживаются map и list для расширений):

code_extensions:
  .py: Python
  .ts: TypeScript
doc_extensions:
  .md: Markdown
  .rst: reStructuredText
config_extensions:
  .yml: YAML
  .json: JSON
exclude:
  - "temp/*"
  - "*.log"

CLI‑параметры

• --source <path|url> — источник
• --output <path> — выходная директория (по умолчанию: source для локальных путей, ./output/<repo> для URL)

Тестирование

Тесты находятся в каталоге tests/:

• test_cache.py
• test_changes.py
• test_scanner.py

Запуск (из корня проекта):

python -m pytest

• --readme — генерировать только README
• --mkdocs — генерировать только MkDocs
• --language ru|en — язык документации
• --include/--exclude — фильтры
• --max-size — максимальный размер файла
• --threads — число потоков LLM
• --cache-dir — директория кэша (по умолчанию .ai_docs_cache)
• --no-cache — отключить LLM‑кэш
• --local-site — добавить site_url и use_directory_urls в mkdocs.yml
• --force — перезаписать README.md, если он уже существует
• --regen — перечень разделов для принудительной перегенерации (через запятую, например architecture,configs,changes, либо all)

Поведение по умолчанию: если не указаны --readme и --mkdocs, генерируются оба артефакта. Разделы в .ai-docs/*.md (включая overview.md) не перегенерируются, если файл уже существует, кроме указанных в --regen. Если количество модулей меньше порога AI_DOCS_REGEN_ALL_THRESHOLD (по умолчанию 50), все разделы перегенерируются автоматически (в том числе overview.md). При запуске без параметров для разделов выводится подсказка с примером --regen. Если модулей больше 100, modules/index.md автоматически разбивается на страницы по 100 элементов с навигацией «←/→». Если конфигов больше 100, configs/index.md также разбивается на страницы по 100 элементов с навигацией «←/→».

MkDocs

Сборка выполняется автоматически в конце генерации:

mkdocs build -f mkdocs.yml

Исключения

Сканер учитывает .gitignore, .build_ignore и дефолтные исключения: .venv, node_modules, ai_docs_site, .ai-docs, .ai_docs_cache, dist, build, т.д.

Разработка и вклад

• Установите зависимости (см. «Быстрый старт»)
• Запускайте через python -m ai_docs ... для отладки
• PR и предложения приветствуются

Лицензия

MIT