Docs-as-Code на практике: автоматизация сборки документации в ODS проекте

В статье рассказывается о переходе к подходу "Docs‑as‑Code" на примере проекта ODS (Open Documentation Standard).

Рассматриваются причины отказа от "Word" подобных инструментов и выбор языка разметки текста AsciiDoc.

Приводится краткое описание функциональных возможностей проекта ODS, версионирование документации в Git, парсинг данных из внешних источников, преобразование и перевод атрибутов БД с помощью LLM-моделей, автоматизация сборки комплектов документов, формирование PDF и публикация документации на сайте используя генератор статических сайтов – Antora.

Проект ODS (Open Documentation Standard) – открытый стандарт и инструментарий для автоматизации процессов создания и поддержки технической документации в ИТ и других проектах. Проект не связан с форматом OpenDocument Spreadsheet (.ods) или проектами Open Data.

В открытом доступе находятся репозиторий и сайт проекта.

Проблемы технической документации

Документация живёт в отдельных файлах, «шаблоны ГОСТ» лежат где‑то в сетевой папке, согласования идут в чате или почте, а изменения в файлах превращаются в бесконечные:

финал_финал_2_исправлено_после_замечаний.docx

С подобными "Word" инструментами всё хорошо, пока документация не развивается и не требует постоянной актуализации. Но когда проекты растут и появляются новые версии, возникают типичные проблемы:

• Проверка и комментарии – сравнение документов плохо похоже на ревью кода, комментарии живут отдельно от истории изменений.
• Повторное использование – «вставить в 17 документов один и тот же фрагмент» почти всегда приводит к поломке стилей и форматированию.
• Стандартизация – трудно гарантировать, что все документы собраны одинаково и в соответствии с шаблонами
• Сборка комплектов – ГОСТ‑комплекты, ведомости и спецификации обычно собираются вручную.

Требования к документированию

Для решения подобных проблем необходимо чтобы документация разрабатывалась как код:

• хранилась в одном месте и версионировалась;
• прозрачно проходила ревью;
• имела единую структуру и возможность повторного использования текста;
• могла синхронизироваться с разработкой – например, отражать актуальное состояние БД и API;
• автоматически собиралась в комплект с едиными стандартами оформления.

Рассматривалось несколько вариантов решения. Поскольку подобных статей достаточно много, перейдем к следующему разделу.

Выбор пал на AsciiDoc и его инфраструктуру

Для большого массива технической документации необходимо иметь следующий функционал:

• include – сборка документа из блоков;
• атрибуты – объявление переменных и констант с повторным использованием;
• сложные таблицы – заголовки, объединение и выравнивание ячеек;
• ссылки между разделами и файлами с контролируемыми наименованиями;
• диаграммы – возможность встраивать UML и BPMN без скриншотов;
• кастомизация стилей оформления;
• кросс‑компиляция в HTML и PDF.

Открытая экосистема Asciidoctor позволяет максимально реализовать эти требования. Язык разметки AsciiDoc предоставляет мощные средства форматирования контента, а инструменты с открытым исходным кодом дают возможность гибко кастомизировать сборку документации под разные требования.

Проект ODS (Open Documentation Standard)

ODS – это не «ещё один стандарт документации». Это попытка собрать воедино подход "Docs‑as‑Code" для документирования проектов.

Проект должен был соответствовать следующим требованиям:

• единый формат исходного кода документации;
• автоматизация сборки документов и комплектов;
• генерация частей документации из БД и OpenAPI;
• использование LLM‑моделей для рутинных задач;
• публикация документации на сайте с печатными формами.

Структура репозитория построена на основе проекта Antora, которая позволяет собирать компоненты сайта из разных репозиториев, веток и тегов, не переключаясь между ними. Остальные инструменты адаптируются под такую структуру.

Как устроен репозиторий

Репозиторий содержит следующие основные папки проекта:

• components/ – компоненты документации (по смыслу: сервисы, системы, гайды);
• components/<name>/modules/<module>/pages – страницы (Antora формирует HTML из pages);
• components/<name>/modules/<module>/partials – переиспользуемые фрагменты текста, подключаемые через include:: (из partials HTML не формируется);
• docker/ – скрипты для локальной сборки и запуска Docker-образов необходимых для сборки проекта;
• tools/ – Ruby‑инструменты автоматизации и конфигурации;
• templates/ – шаблоны документации;
• antora-playbook.yml – файл конфигурации Antora.

Такая структура позволяет реализовать модульность документации и параллельно вести несколько проектов или систем в одном репозитории.

Система контроля версий (Git) позволяет поддерживать версии комплектов документации используя теги и ветки.

Автоматизация в ODS

Теперь про то, что обычно «ломает» мечту о "Docs‑as‑Code":

• печать по ГОСТ;
• автоматическая генерация контента из БД и API;
• сборка всего комплекта документов. 

Главный оркестратор – скрипт tools/start.rb проходит по компонентам из файла конфигурации и, в зависимости от флагов, выполняет:

• Конвертацию BPMN (Node + Puppeteer);
• Конвертацию Draw.io (Node);
• Генерацию AsciiDoc из OpenAPI / Swagger (Ruby);
• Генерацию AsciiDoc и диаграмм из PostgreSQL, преобразование и перевод атрибутов (Ruby, Ollama);
• Генерацию служебных списков, ссылок и таблиц о составе документации, имен файлов и названий документов, количестве листов в документах и т.п. (Ruby);
• Генерацию листов утверждения, спецификаций и ведомостей (Ruby, Asciidoctor PDF);
• Генерацию PDF (Asciidoctor PDF + кастомные конвертеры).

Запуск командой:

ruby tools/start.rb

Запускается скрипт start.rb и выполняется сборка проекта согласно сценарию, заданному в файле config.yml. В результате сборки проекта появляются готовые к печати и/или публикации на сайте PDF документы.

Формирование PDF документов

Инструменты Asciidoctor PDF предоставляют широкие возможности настройки тем оформления документов, но оформление в соответствии с ГОСТ или шаблонами часто упирается в проблемы:

• рамки и штампы;
• нестандартные титульные страницы;
• особые правила нумерации списков и колонтитулов.

Поэтому в ODS генерация PDF построена так:

1. Asciidoctor PDF делает базовую вёрстку контента;
2. Кастомные Ruby‑конвертеры оформляют рамки, титульные страницы, листы утверждения и стилизуют списки.
   

На выходе получается документация оформленная в соответствии с заложенными к ее оформлению требованиями.

Документация из внешних источников

В настоящее время ODS поддерживает генерацию документации из следующих источников:

1. PostgreSQL – таблицы, поля, комментарии, ERD‑диаграммы;
2. OpenAPI / Swagger – структура API, методы, параметры и ответы (могут использоваться как ссылки на swagger, так и файлы в в репозитория json/yml).

В результате парсинга БД и API формируются отдельные asciidoc документы для подключения к основным файлам документации.

Модели ИИ и Ollama

Для преобразования и перевода названий таблиц и атрибутов в полученной документации, при незаполненных в БД полях comment, используется словарь переводов и сервер Ollama предоставляющий CLI и HTTP API с различными языковыми моделями (LLM).

Для задач преобразования и перевода используется промт-файл database_translations.prompt, который отправляется в модель вместе с данными.

			Переведи следующие поля базы данных на <%= target_language %> язык:

<% fields.each_with_index do |field, index| %>
<%= index + 1 %>. <%= field %>
<% end %>

Требования:
<% if target_language == "русский" %>
- Переведи каждое слово точно на русский
- Замени подчеркивания на пробелы
- ВАЖНО: ВСЕГДА начинай перевод с ЗАГЛАВНОЙ буквы (первая буква должна быть заглавной)
- ВАЖНО: Сохраняй число (единственное/множественное) - если оригинал в единственном числе (city, airport, user), то перевод тоже в единственном числе (Город, Аэропорт, Пользователь). Если оригинал во множественном числе (cities, airports, users), то перевод во множественном числе (Города, Аэропорты, Пользователи)
- Отвечай ТОЛЬКО переводом, без объяснений
- Не добавляй слова "поле", "атрибут", "данные" если их нет в оригинале

Примеры (обрати внимание - все переводы начинаются с заглавной буквы и сохраняют число):

user_id → Идентификатор пользователя
created_at → Дата создания
booking_number → Номер бронирования
passenger_name → Имя пассажира
city → Город (единственное число)
cities → Города (множественное число)
		

Словарь это yml-файл генерируемый скриптом который в свою очередь использует сервис Ollama. При последующих переводах словарь имеет приоритет, а LLM используется пакетно, что позволяет сохранить точность и обеспечить приемлемую скорость при повторных переводах.

			---
translations:
  user_id: Идентификатор пользователя
  created_at: Дата создания
  updated_at: Дата обновления
  aircrafts_data: Данные о самолетах
  airport_name: Название аэропорта
  city: Город
  airports_data: Данные о аэропортах

		

Словарь можно править вручную. При появлении новых данных в БД, они транслируются в лог-файл tools/log/database_translations_log.txt.

			# Лог переводов LLM
# Обновляется при каждом запуске

2025-12-18 23:27:57 | airport_name → Название аэропорта
2025-12-18 23:27:57 | city → Город
2025-12-18 23:27:57 | airports_data → Данные о аэропортах

		

Логирование удобно для контроля перевода, а при необходимости и ручной правки последних изменений в словаре. Язык перевода может быть задан в файле config.yml в зависимости от используемого в БД.

Сайт документации и Antora

Для публикации документации используется генератор статических сайтов Antora. Он обеспечивает:

• компонентную модель документации;
• встроенное версионирование;
• сборку сайта из разных репозиториев, веток и тегов;
• поддержку диаграмм через сервер Kroki.

Автоматически сформированные на предыдущем этапе списки используются Antora для формирования ссылок в навигации и к сформированным PDF‑документам.

Запуск командой:

antora antora-playbook.yml

Antora в ODS отвечает только за сборку сайта. Файл конфигурации antora-playbook.yml используется для самой Antora и установки атрибутов-ключей для условных операторов в Asciidoc и Ruby, которые разделяют сборку PDF и сайта.

Итог

ODS – это попытка сделать техническую документацию:

1. воспроизводимой;
2. версионируемой;
3. связанной с реальными источниками данных;
4. удобной для проверки;
5. автоматически собираемой в готовый комплект.

На практике это помогает поддерживать документацию в актуальном состоянии, ускоряет погружение в проект новых сотрудников, а масштабирование проекта не превращает его документацию в “кладбище файлов”.

Если вы хотите повторить этот подход у себя, практический совет прост: начните с AsciiDoc, подключите Git, научитесь собирать PDF. Всё остальное можно подключать постепенно, когда появится стабильная и понятная структура документации.

Реализацию проекта ODS и публикуемую с его помощью документацию можно посмотреть в открытом репозитории и на сайте. Так же на сайте можно посмотреть ознакомительное видео проекта.