ai-docs-gen 0.1.2__py3-none-any.whl

ai_docs/summary.py

@@ -0,0 +1,238 @@
+from pathlib import Path
+from typing import Dict, List
+
+from .tokenizer import chunk_text
+from .utils import ensure_dir
+
+
+SUMMARY_PROMPT = """
+Ты эксперт по технической документации. Сформируй краткое, но информативное описание файла для включения в документацию.
+Укажи назначение, ключевые сущности и важные настройки. Если файл конфигурационный — перечисли ключевые параметры/секции.
+Ответ строго в Markdown, без заголовка. Не используй блоки кода и не оборачивай текст в ```markdown.
+""".strip()
+
+MODULE_SUMMARY_PROMPT = """
+Ты технический писатель. Сформируй документацию модуля в стиле Doxygen.
+Сначала дай краткое верхнеуровневое описание модуля (2–4 предложения).
+Затем, если есть важные структуры данных/типы, добавь блок:
+Ключевые структуры данных
+<имя> — <краткое описание>
+
+Далее перечисли функции/процедуры и классы строго в Doxygen‑формате.
+Для функций/процедур используй формат:
+
+<сигнатура>
+<краткое назначение одной строкой>
+Аргументы
+<имя> — <описание>
+Возвращает
+<описание>
+Исключения
+<описание>
+
+Для классов используй формат:
+class <имя>
+<краткое назначение одной строкой>
+Поля
+<имя> — <описание>
+Методы
+<сигнатура> — <краткое назначение>
+
+Если аргументов/возвращаемого значения/исключений/полей нет — соответствующий блок пропускай.
+Разделяй сущности строкой из трёх дефисов: `---`.
+Не используй заголовки Markdown, списки, подзаголовки вроде "Основные функции".
+Ответ строго в Markdown, без заголовка документа, сохраняя последовательность блоков.
+""".strip()
+
+MODULE_SUMMARY_REFORMAT_PROMPT = """
+Переформатируй текст в строгий Doxygen‑стиль для модуля.
+Требования:
+- Без заголовков Markdown, без списков, без блоков кода.
+- Структура: краткое описание модуля; затем (если есть) "Ключевые структуры данных" с линиями "<имя> — <описание>".
+- Далее только сущности (функции/процедуры/классы) в формате:
+<сигнатура>
+<краткое назначение одной строкой>
+Аргументы
+<имя> — <описание>
+Возвращает
+<описание>
+Исключения
+<описание>
+Для классов:
+class <имя>
+<краткое назначение одной строкой>
+Поля
+<имя> — <описание>
+Методы
+<сигнатура> — <краткое назначение>
+
+Если блок пустой — не выводи его. Между сущностями ставь строку `---`.
+Ответ строго в Markdown без заголовка документа.
+""".strip()
+
+CONFIG_SUMMARY_PROMPT = """
+Ты технический писатель. Сформируй описание конфигурационного файла в универсальном стиле.
+Сначала дай краткое описание файла (2–4 предложения).
+Затем блок:
+Секции и ключи
+<секция/ключ> — <описание>
+
+Далее (если есть важные параметры) добавь блок:
+Важные параметры
+<параметр> — <описание>
+
+Не используй заголовки Markdown, списки, нумерацию и блоки кода.
+Ответ строго в Markdown без заголовка документа, соблюдай указанные блоки.
+""".strip()
+
+CONFIG_SUMMARY_REFORMAT_PROMPT = """
+Переформатируй текст в универсальный конфиг-стиль.
+Требования:
+- Без заголовков Markdown, списков, нумерации и блоков кода.
+- Структура: краткое описание файла; затем блок "Секции и ключи" с линиями "<секция/ключ> — <описание>".
+- Далее (если есть) блок "Важные параметры" с линиями "<параметр> — <описание>".
+Если блок пустой — не выводи его.
+Ответ строго в Markdown без заголовка документа.
+""".strip()
+
+
+def _needs_doxygen_fix(text: str) -> bool:
+    if "```" in text:
+        return True
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            return True
+        if stripped.startswith(("-", "*", "•")):
+            return True
+        if stripped[:2].isdigit() and stripped[1] == ".":
+            return True
+    lowered = text.lower()
+    noisy_markers = [
+        "основные функции",
+        "основные возможности",
+        "обработка ошибок",
+        "интеграции",
+        "ключевые структуры данных:",
+        "##",
+    ]
+    return any(marker in lowered for marker in noisy_markers)
+
+
+def _normalize_module_summary(
+    summary: str, llm_client, llm_cache: Dict[str, str]
+) -> str:
+    if not _needs_doxygen_fix(summary):
+        return summary
+    messages = [
+        {"role": "system", "content": MODULE_SUMMARY_REFORMAT_PROMPT},
+        {"role": "user", "content": summary},
+    ]
+    return llm_client.chat(messages, cache=llm_cache).strip()
+
+
+def _normalize_config_summary(summary: str, llm_client, llm_cache: Dict[str, str]) -> str:
+    if not _needs_doxygen_fix(summary):
+        return _format_config_blocks(summary)
+    messages = [
+        {"role": "system", "content": CONFIG_SUMMARY_REFORMAT_PROMPT},
+        {"role": "user", "content": summary},
+    ]
+    return _format_config_blocks(llm_client.chat(messages, cache=llm_cache).strip())
+
+
+def _format_config_blocks(text: str) -> str:
+    lines = [line.rstrip() for line in text.strip().splitlines() if line.strip()]
+    if not lines:
+        return text.strip()
+    output: List[str] = []
+    i = 0
+    headers = {"Секции и ключи", "Важные параметры"}
+    while i < len(lines):
+        line = lines[i].strip()
+        if line in headers:
+            entries: List[str] = []
+            i += 1
+            while i < len(lines) and lines[i].strip() not in headers:
+                entries.append(lines[i].strip())
+                i += 1
+            output.append(line)
+            if entries:
+                output.append("<br>\n".join(entries))
+            continue
+        output.append(line)
+        i += 1
+    return "\n\n".join(output).strip()
+
+
+def _strip_fenced_markdown(text: str) -> str:
+    stripped = text.strip()
+    if stripped.startswith("```"):
+        lines = stripped.splitlines()
+        if len(lines) >= 2 and lines[0].startswith("```") and lines[-1].strip() == "```":
+            return "\n".join(lines[1:-1]).strip()
+    return text
+
+
+def summarize_file(
+    content: str,
+    file_type: str,
+    domains: List[str],
+    llm_client,
+    llm_cache: Dict[str, str],
+    model: str,
+    detailed: bool = False,
+) -> str:
+    chunks = chunk_text(content, model=model, max_tokens=1800)
+    summaries = []
+    for chunk in chunks:
+        if detailed and file_type == "config":
+            prompt = CONFIG_SUMMARY_PROMPT
+        else:
+            prompt = MODULE_SUMMARY_PROMPT if detailed else SUMMARY_PROMPT
+        if not detailed and (file_type == "infra" or domains):
+            prompt = SUMMARY_PROMPT + "\nФайл относится к инфраструктуре: " + ", ".join(domains)
+        messages = [
+            {"role": "system", "content": prompt},
+            {"role": "user", "content": chunk},
+        ]
+        summaries.append(_strip_fenced_markdown(llm_client.chat(messages, cache=llm_cache).strip()))
+
+    if len(summaries) == 1:
+        result = summaries[0]
+        if detailed and file_type == "config":
+            return _normalize_config_summary(result, llm_client, llm_cache)
+        if detailed:
+            return _normalize_module_summary(result, llm_client, llm_cache)
+        return result
+
+    combined = "\n\n".join(summaries)
+    if detailed and file_type == "config":
+        messages = [
+            {"role": "system", "content": CONFIG_SUMMARY_REFORMAT_PROMPT},
+            {"role": "user", "content": combined},
+        ]
+    elif detailed:
+        messages = [
+            {"role": "system", "content": MODULE_SUMMARY_REFORMAT_PROMPT},
+            {"role": "user", "content": combined},
+        ]
+    else:
+        messages = [
+            {"role": "system", "content": "Собери единое краткое резюме для документации на основе частей ниже. Ответ в Markdown."},
+            {"role": "user", "content": combined},
+        ]
+    result = _strip_fenced_markdown(llm_client.chat(messages, cache=llm_cache).strip())
+    if detailed and file_type == "config":
+        return _normalize_config_summary(result, llm_client, llm_cache)
+    if detailed:
+        return _normalize_module_summary(result, llm_client, llm_cache)
+    return result
+
+
+def write_summary(summary_dir: Path, rel_path: str, summary: str) -> Path:
+    ensure_dir(summary_dir)
+    safe_name = "".join(c if c.isalnum() else "_" for c in rel_path).strip("_").lower()
+    out_path = summary_dir / f"{safe_name}.md"
+    out_path.write_text(summary, encoding="utf-8")
+    return out_path

ai_docs/tokenizer.py

@@ -0,0 +1,26 @@
+from typing import List
+
+import tiktoken
+
+
+def get_encoding(model: str):
+    try:
+        return tiktoken.encoding_for_model(model)
+    except KeyError:
+        return tiktoken.get_encoding("cl100k_base")
+
+
+def count_tokens(text: str, model: str) -> int:
+    enc = get_encoding(model)
+    return len(enc.encode(text))
+
+
+def chunk_text(text: str, model: str, max_tokens: int) -> List[str]:
+    enc = get_encoding(model)
+    tokens = enc.encode(text)
+    chunks = []
+    for i in range(0, len(tokens), max_tokens):
+        chunk = tokens[i:i + max_tokens]
+        chunks.append(enc.decode(chunk))
+    return chunks
+

ai_docs/utils.py

@@ -0,0 +1,43 @@
+import hashlib
+import os
+from pathlib import Path
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_text(text: str) -> str:
+    return sha256_bytes(text.encode("utf-8", errors="ignore"))
+
+
+def read_text_file(path: Path) -> str:
+    return path.read_text(encoding="utf-8", errors="ignore")
+
+
+def safe_slug(path: str) -> str:
+    return "".join(c if c.isalnum() else "_" for c in path).strip("_").lower()
+
+
+def ensure_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def is_binary_file(path: Path, sample_size: int = 2048) -> bool:
+    try:
+        with path.open("rb") as f:
+            chunk = f.read(sample_size)
+        if b"\x00" in chunk:
+            return True
+        return False
+    except OSError:
+        return True
+
+
+def is_url(value: str) -> bool:
+    return value.startswith("http://") or value.startswith("https://") or value.startswith("git@")
+
+
+def to_posix(path: Path) -> str:
+    return path.as_posix()
+

ai_docs_gen-0.1.2.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: ai-docs-gen
+Version: 0.1.2
+Summary: CLI-инструмент для генерации технической документации по коду и конфигурациям
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: tiktoken
+Requires-Dist: pyyaml
+Requires-Dist: pathspec
+Requires-Dist: tomli
+Requires-Dist: python-dotenv
+Requires-Dist: mkdocs
+Requires-Dist: mkdocs-mermaid2-plugin
+Requires-Dist: pymdown-extensions
+
+# ai_docs — генератор технической документации
+
+## Обзор
+`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) Установка зависимостей:
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Альтернатива (установка как пакет):
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install ai-docs-gen
+```
+
+Локальная установка в editable‑режиме:
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e .
+```
+
+2) Настройка `.env` (пример — `.env.example`):
+```env
+OPENAI_API_KEY=your_api_key_here
+OPENAI_BASE_URL=https://api.openai.com/v1
+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
+```
+
+3) Генерация README и MkDocs:
+```bash
+python -m ai_docs --source .
+```
+
+Альтернативно:
+```bash
+python ai_docs --source .
+```
+
+Если установлен как пакет:
+```bash
+ai-docs --source .
+```
+
+## Примеры использования
+
+Локальная папка:
+```bash
+python -m ai_docs --source /path/to/project
+```
+
+Локальный git‑проект:
+```bash
+python -m ai_docs --source ~/projects/my-repo
+```
+
+Удалённый репозиторий:
+```bash
+python -m ai_docs --source https://github.com/org/repo.git
+```
+
+Только README:
+```bash
+python -m ai_docs --source . --readme
+```
+
+Только MkDocs:
+```bash
+python -m ai_docs --source . --mkdocs
+```
+
+Локальный режим для MkDocs:
+```bash
+python -m ai_docs --source . --mkdocs --local-site
+```
+
+## Что генерируется
+- `README.md` — краткое описание проекта
+- `.ai-docs/` — страницы документации
+- `.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 для расширений):
+```yaml
+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`
+
+Запуск (из корня проекта):
+```bash
+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`, если он уже существует
+
+Поведение по умолчанию: если не указаны `--readme` и `--mkdocs`, генерируются оба артефакта.
+
+## 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

ai_docs_gen-0.1.2.dist-info/RECORD

@@ -0,0 +1,19 @@
+ai_docs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ai_docs/__main__.py,sha256=yNFl5cGhWoeZLOulgfPCd-pOwjq0dclhAyB-OiG-cvE,512
+ai_docs/cache.py,sha256=Z3Mwg2QEYZNaC6bRyv6Py0FcFDV0d9KnyFiBf-EsyFE,1784
+ai_docs/changes.py,sha256=tA6kf79XPiywqWBBfBaqf-upRyowyInsw-BFYOIUAmA,973
+ai_docs/cli.py,sha256=XhZO6b49lYGqefITwu-R57-pN6t5esyARGlcMz7cXAA,3639
+ai_docs/domain.py,sha256=HrbdDw_Qxe1gk7J4dzYN1MHbYXDGY3-Tyr5--LgSjzc,6253
+ai_docs/generator.py,sha256=n_sdUxHPFF4c4CPplbxEGDYmK32tfXq2w7a1sEVqa8E,41146
+ai_docs/llm.py,sha256=BCVcMM1X_B_LMEuyLBM6jFNz8jYONikM4pEJVhJ16c0,2633
+ai_docs/mkdocs.py,sha256=Zh23S3T3gTou2TryfLSwDWzWTwDtLYf5kM5eTnLpGek,5243
+ai_docs/scanner.py,sha256=KwJnu3GYL1lABeSVTlxlrddOuKkHyomQ39g6AdPbPh0,8793
+ai_docs/summary.py,sha256=01cJer00yJnT7p7nKgvPy-H37A3PqHHVeA8RuzkwX8M,10357
+ai_docs/tokenizer.py,sha256=G8btLH0IRJCx4b2jM8lWSzS0dcOZP-sAqwWYUQ5jF40,614
+ai_docs/utils.py,sha256=kJKgO2R8ZQa58MBUZK2oEr03wFvVkRaWZYruxxJigGo,993
+ai_docs/assets/mermaid.min.js,sha256=LPe7bNxKbqlto9MkpER9gwDR2nA85fMTEWCGQsD4Ymk,2908475
+ai_docs_gen-0.1.2.dist-info/METADATA,sha256=0-ncf5tDSlADitUF5erpLL6Ew2Yl02HYDcoVnV_ejIM,7723
+ai_docs_gen-0.1.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ai_docs_gen-0.1.2.dist-info/entry_points.txt,sha256=C5tKlnOjrwbPgVbOB_zA8WeFjk05DXsMhq2UgTw5BDk,45
+ai_docs_gen-0.1.2.dist-info/top_level.txt,sha256=Uqf4JT1_bI7m3yV5gs5kuL5Nmws5E2XT3W9yajZck2c,8
+ai_docs_gen-0.1.2.dist-info/RECORD,,

ai_docs_gen-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ai_docs_gen-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ai-docs = ai_docs.cli:main

ai_docs_gen-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+ai_docs