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‑моделей для рутинных задач;
- публикация документации на сайте с печатными формами.
Как устроен репозиторий
Репозиторий содержит следующие основные папки проекта:
- 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) позволяет поддерживать версии комплектов документации используя теги и ветки.
Генератор статических сайтов Antora позволяет собирать компоненты сайта из разных репозиториев, веток и тегов, не переключаясь между ними.
Автоматизация в 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 + кастомные конвертеры).
Запуск командой:
Запускается скрипт start.rb и выполняется сборка проекта согласно сценарию, заданному в файле config.yml. В результате сборки проекта появляются готовые к печати и/или публикации на сайте PDF документы.
Формирование PDF документов
Инструменты Asciidoctor PDF предоставляют широкие возможности настройки тем оформления документов, но оформление в соответствии с ГОСТ или шаблонами часто упирается в проблемы:
- рамки и штампы;
- нестандартные титульные страницы;
- особые правила нумерации списков и колонтитулов.
Поэтому в ODS генерация PDF построена так:
- Asciidoctor PDF делает базовую вёрстку контента;
- кастомные Ruby‑конвертеры оформляют рамки, титульные страницы, листы утверждения и стилизуют списки.
Документация из внешних источников
В настоящее время ODS поддерживает генерацию документации из следующих источников:
- PostgreSQL – таблицы, поля, комментарии, ERD‑диаграммы;
- OpenAPI / Swagger – структура API, методы, параметры и ответы (могут использоваться как ссылки на swagger, так и файлы в в репозитория json/yml).
В результате парсинга БД и API формируются отдельные asciidoc документы для подключения к основным файлам документации.
Модели ИИ и Ollama
Для преобразования и перевода названий таблиц и атрибутов в полученной документации, при незаполненных в БД полях comment, используется словарь терминов и локальные LLM‑модели c Ollama.
Для задач преобразования и перевода используется prompt-файл database_translations.prompt, который отправляется в модель вместе с данными.
Словарь это yml-файл первоначально генерируемый скриптом который использует сервис Ollama. При последующих переводах словарь имеет приоритет, а LLM используется пакетно, что позволяет сохранить точность и обеспечить приемлемую скорость при повторных переводах.
Словарь можно править вручную. При появлении новых данных в БД, они транслируются в tools/log/database_translations_log.txt.
Логирование удобно для контроля перевода, а при необходимости и ручной правки последних изменений в словаре. Язык перевода может быть задан в файле config.yml в зависимости от используемого в БД.
Сайт документации и Antora
Для публикации документации используется генератор статических сайтов Antora. Он обеспечивает:
- компонентную модель документации;
- встроенное версионирование;
- сборку сайта из разных репозиториев, веток и тегов;
- поддержку диаграмм через сервер Kroki.
Автоматически сформированные на предыдущем этапе списки используются Antora для формирования ссылок в навигации и к сформированным PDF‑документам.
Запуск командой:
Antora в ODS отвечает только за сборку сайта. Файл конфигурации antora-playbook.yml используется для самой Antora и установки атрибутов-ключей для условных операторов в Asciidoc и Ruby, которые разделяют сборку PDF и сайта.
Итог
ODS – это попытка сделать техническую документацию:
- воспроизводимой;
- версионируемой;
- связанной с реальными источниками данных;
- удобной для проверки;
- автоматически собираемой в готовый комплект.
На практике это помогает поддерживать документацию в актуальном состоянии, ускоряет погружение в проект новых сотрудников, а масштабирование проекта не превращает его документацию в “кладбище файлов”.
Если вы хотите повторить этот подход у себя, практический совет прост: начните с AsciiDoc, подключите Git, научитесь собирать PDF. Всё остальное можно подключать постепенно, когда появится стабильная и понятная структура документации.
Реализацию проекта ODS и публикуемую с помощью него документацию можно посмотреть в открытом репозитории и на сайте. Так же на сайте можно посмотреть ознакомительное видео проекта.