Сценарий 03: Генерация документации

Технический писатель создаёт документацию по API, обзоры модулей и диаграммы из кода с помощью анализа CPG.

Содержание

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

# Выберите сценарий документации
/select 03

Как это работает

Классификация интентов

DocumentationIntentDetector классифицирует запросы в один из 10 интентов (+ запасной вариант), отсортированных по приоритету. Каждый интент имеет EN и RU ключевые слова с морфологическим сопоставлением.

Интент Приоритет Описание
mvd_doc 3 Minimum Viable Documentation проекта
module_overview 5 Обзор модуля/подсистемы
coverage_doc 7 Анализ покрытия документацией
diagram_doc 8 Диаграммы (граф вызовов, компоненты, зависимости)
pipeline_doc 10 Документация конвейера обработки
business_logic_doc 12 Извлечение бизнес-логики
type_doc 14 Документация типов и конвертаций
function_doc 20 Документация одной функции
usage_example 30 Примеры использования
api_reference 40 Справочник API

Если ни один интент не совпал, используется запасной general_documentation (confidence=0.5).

Детектор также извлекает: - target — имя функции или модуля из запроса (через regex-паттерны и семантические маппинги) - format — формат вывода: markdown (по умолчанию), html, rst, latex - diagram_type — для diagram_doc: component, dependency или callgraph

Двухфазная архитектура

S03 использует двухфазный подход:

Фаза 1: На основе обработчиков (без LLM). Функция integrate_handlers() пробует 8 зарегистрированных шаблонных обработчиков. Каждый обработчик создаёт структурированную документацию напрямую из данных CPG с помощью DocumentationReportFormatter. Если обработчик совпал с обнаруженным интентом и нашёл результаты, ответ возвращается без вызова LLM.

Фаза 2: Запасной вариант с LLM. Если ни один обработчик не совпал, запускается полный конвейер: 4-фазный CPG-поиск собирает методы, CallGraphAnalyzer обогащает паттернами использования, затем LLM генерирует документацию с графовым контекстом.

Запрос -> DocumentationIntentDetector -> integrate_handlers()
  |                                          |
  |  Фаза 1: Обработчик совпал?    Да -> Структурированный отчёт (без LLM)
  |                                 Нет -> Фаза 2: Полный конвейер
  |
  Фаза 2: CPG-поиск (4 фазы) -> CallGraphAnalyzer
           -> LLM с графовым контекстом -> Документация

Восемь обработчиков документации

8 обработчиков зарегистрированы в HandlerRegistry("documentation"):

Обработчик Приоритет Интент
MVDDocHandler 3 mvd_doc
CoverageDocHandler 7 coverage_doc
DiagramDocHandler 8 diagram_doc
FunctionDocHandler 10 function_doc
BusinessLogicDocHandler 12 business_logic_doc
TypeDocHandler 14 type_doc
PipelineDocHandler 15 pipeline_doc
ModuleOverviewHandler 20 module_overview

Все обработчики наследуют DocumentationHandler (расширяет BaseHandler), который предоставляет отслеживание инкрементальных сессий документирования — _get_doc_session(), _update_doc_session() и _get_session_delta() позволяют отслеживать, какие функции/модули были задокументированы в рамках нескольких запросов.

Конвейер CPG-поиска

Фаза запасного варианта с LLM использует 4-фазный конвейер CPG-поиска для нахождения релевантных методов:

Фаза 1: Прямой поиск функции

extract_function_names_from_query() извлекает имена функций с помощью 8 regex-паттернов:

  1. В обратных кавычках: `funcName`
  2. Синтаксис вызова: funcName(
  3. Фразы «function X» / «method X»
  4. Обратный порядок «X function»
  5. Паттерны «for X» / «of X»
  6. Идентификаторы CamelCase (например, ExecInitNode)
  7. Идентификаторы snake_case (например, heap_insert)
  8. Доменно-специфичные соглашения именования из плагина

Найденные имена запрашиваются напрямую в nodes_method для точных совпадений.

Если прямых результатов нет, _get_documentation_keywords() загружает маппинги ключевых слов к паттернам из доменного плагина и выполняет поиск по совпавшим паттернам через search_methods_by_name_pattern().

Если результатов всё ещё нет, ключевые слова и псевдонимы подсистем загружаются из доменного плагина. Запрос сопоставляется с именами подсистем через keyword_match_morphological(), затем get_methods_by_subsystem() извлекает методы.

Фаза 4: Запасной поиск по ключевым словам

В крайнем случае _extract_significant_words() извлекает значимые слова из запроса (отфильтровывая стоп-слова) и выполняет поиск по каждому слову отдельно.

Интеграция CallGraphAnalyzer

После извлечения методов CallGraphAnalyzer(cpg) из src/analysis/ обогащает каждый метод анализом паттернов использования:

  • find_all_callers(method_name, max_depth) — кто использует этот метод
  • find_all_callees(method_name, max_depth) — что вызывает этот метод
  • analyze_impact(method_name) — оценка важности для приоритета документирования

Анализатор определяет: - Ключевые методы — методы с высоким impact_score приоритизируются для тщательного документирования - Точки входа — методы без вызывающих или совпадающие с паттернами точек входа из доменного плагина - Публичный API — методы с множеством вызывающих отмечаются как публичный API - Примеры вызовов — прямые вызывающие предоставляют контекст использования для документации

Типы документации

Документация функции

Генерирует документацию API для отдельных функций с сигнатурой, параметрами, описанием, примерами использования и связанными функциями (вызывающие/вызываемые из графа вызовов).

Обзор модуля

Генерирует архитектурную документацию для модулей/подсистем, включая структуру компонентов, ключевые функции, поток данных и межмодульные зависимости.

MVD (Minimum Viable Documentation)

Генерирует Minimum Viable Documentation уровня проекта — структурированный обзор, охватывающий архитектуру, ключевые модули, точки входа и поверхность API.

Отчёт о покрытии

Анализирует покрытие документацией — выявляет недокументированные функции, вычисляет коэффициент покрытия комментариями и выделяет пробелы в документации.

Диаграммы

Генерирует диаграммы Mermaid из данных CPG: - Граф вызовов — отношения вызовов между функциями - Диаграмма компонентов — архитектура подсистем/модулей - Диаграмма зависимостей — граф зависимостей файлов/модулей

diagram_type автоматически определяется из запроса (component, dependency или callgraph).

Документация конвейера

Документирует конвейеры обработки данных и потоки выполнения — трассирует обработку запросов от входа до выхода через граф вызовов.

Извлечение бизнес-логики

Извлекает бизнес-правила, инварианты и логику валидации из кода — определяет условную логику, утверждения и проверки ограничений.

Документация типов

Документирует системы типов, преобразования типов и операции приведения — анализирует поток типов через сигнатуры функций и возвращаемые типы.

Форматы экспорта

Документация может быть экспортирована на внешние платформы:

  • GitBook — GitBookExporter(output_dir) генерирует SUMMARY.md со структурой глав и отдельные markdown-файлы
  • Docusaurus — DocusaurusExporter(output_dir) генерирует MDX-файлы с frontmatter и конфигурацией боковой панели

DocumentationReportFormatter предоставляет 8 методов форматирования, соответствующих каждому типу документации: format_function_documentation, format_module_overview, format_pipeline_documentation, format_coverage_report, format_diagram_documentation, format_type_documentation, format_mvd_document, format_business_logic_report.

Использование CLI

# Генерация документации функции
python -m src.cli query "Generate documentation for heap_insert"

# Обзор модуля
python -m src.cli query "Document the executor module architecture"

# Покрытие документацией
python -m src.cli query "Show documentation coverage for the storage subsystem"

# Генерация диаграмм
python -m src.cli query "Generate call graph diagram for the parser module"

# Полная генерация документации
python -m src.cli.generate_docs full --output ./docs/generated --language en

# Генерация определённой секции
python -m src.cli.generate_docs section mvd_doc --language en

# Экспорт в GitBook/Docusaurus
python -m src.cli.export_docs --format gitbook --output ./gitbook-docs
python -m src.cli.export_docs --format docusaurus --output ./docusaurus-docs

Примеры вопросов

  • «Создать документацию для [имя_функции]»
  • «Документировать архитектуру [модуля]»
  • «Показать покрытие документацией для [подсистемы]»
  • «Сгенерировать диаграмму графа вызовов для [модуля]»
  • «Сгенерировать Minimum Viable Documentation для проекта»
  • «Извлечь бизнес-логику из [модуля]»
  • «Документировать преобразования типов в [подсистеме]»
  • «Объяснить конвейер обработки запросов»
  • «Показать примеры использования для [функции]»
  • «Перечислить все функции публичного API в [модуле]»

S03 vs S01 vs S11: S03 генерирует артефакты документации (документация API, обзоры модулей, диаграммы, отчёты о покрытии) из кода. S01 (ознакомление) помогает разработчикам исследовать и понимать незнакомые кодовые базы в интерактивном режиме. S11 (архитектура) фокусируется на структурном анализе — циклы зависимостей, нарушения слоёв, метрики связности. Все три используют данные CPG и CallGraphAnalyzer, но служат разным целям: S03 создаёт документацию, S01 отвечает на вопросы исследования, S11 обнаруживает архитектурные проблемы.