Продолжая тему использования Asciidoc (и других аналогичных форматов) для организации процессов непрерывного документирования, хочу рассмотреть тему автоматический генерации технической документации.

Автоматическая генерация документациираспространенный, но очень расплывчатый термин. Я понимаю под этим термином извлечение для представления в удобном виде информации, содержащейся в исходном коде и настройках документируемой программы (информационной системы).

Общая схема автоматической генерации документации

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

• преобразование исходного кода в структурированный формат. Шаг обусловлен тем, что для получения документов используются шаблонизаторы. Все современные технологии, связанные с генерацией человеко-читаемых документов, пользовательских интерфейсов, программного кода, активно используют шаблонизаторы, подключаемые в виде библиотек или реализованные внутри программного кода. Вход для шаблонизатораструктура данных, которую легко получить из файлов в форматах JSON/YAML или XML;
• преобразование структурированного формата в один из форматов документации (обычно Asciidoc, DITA, Docbook, Markdown, reStructuredText).

За исключением самых простых случаев документация готовится в различных выходных форматах (html, docx, odt, pdf и т.п.) и собирается из разных источников (в том числе не автоматически генерируемых) поэтому целесообразно использовать специальные форматы, для подготовки документации. Предположим, необходимо подготовить документацию по стандартам ЕСКД? Эта проблема, описана в предыдущей статье. При решении проблем автоматической генерации хватает проблем и без требований ГОСТ.

Общая схема генерации документации выглядит следующим образом:

Рассмотрим практические приёмы, которые можно использовать при реализации ИТ-проектов. Для примеров будем использовать Asciidoc, однако приёмы применимы к любым языкам разметки текста(reStructuredText, Markdown), и текстовым маркапам для построения диаграмм (рекомендую проект kroki, который позволяет быстро ознакомиться и внедрить наиболее популярные средства построения диаграмм).

Преобразование исходного кода в структурированный формат

Единых подходов к превращению исходного кода в структурированный формат не существует. Рассмотрим наиболее частые варианты.

Информация для документации извлекается из структуры исходного кода

Как правило, используются дополнительные средства языка, обычно комментарии в специальном формате (комментарии Javadoc, ReST и т.п.) и аннотации.

Средств, обеспечивающих преобразование исходного кода в документацию, причём очень зрелых, много. Можно смело брать и использовать подходящие для конкретного проекта. Разработка собственных средств затратна. Мы пошли указанным путём только раз, разрабатывая проект для миграции структуры базы данных. Целесообразность определялась использованием средства во всех наших проектах и желанием попробовать свои силы.

Следующие подходы более гибки с точки зрения настройки автоматической генерации документации в реализуемых проектах.

Структурированный формат получается как один из результатов исполнения исходного кода

При данном подходе считывается и сохраняется в структурированный формат состояния объектов (например, структуры базы данных, конфигурации развернутой среды информационной системы и т.п.), создаваемых в результате работы приложения.

Отдельно отметим использование для документирвоания логов. Типовой примертесты. Например, большинство инструментов для тестирования выдают результаты в формате Junit xml report. Это, позволяет сделать универсальные инструменты генерации отчётности по тестам, самый известный, наверноеAllure Framework.

В этой статье показано, как используют JSON-файлы, которые генерирует при работе Cucumber, как документация строится на основе логов, создаваемых в результате работы тестов.

Типовой пример создания документации на основе считывания состояния объектов, создаваемых в результате работы приложения,документирование структуры БД. В конце раздела приведен пример, иллюстрирующий данный подход.

Исходный код сразу представляет собой структурированный формат

Многие языки уже реализованы в структурированном формате (например, xsd-схемы, OpenAPI, различные DSL для описания предметной области, файлы настроек).

Иногда проводят предварительную обработку этих форматов, например, объединение спецификации в единую иерархическую структуру (так называемая операция flatten).

Частным (и частым) случаем является ситуация, когда настройки содержатся в базе данных.

Примергенерация документации по структуре базы данных

Пример иллюстрирует достаточно частую ситуацию, когда информация для документации хранится в таблицах СУБД.

Создаём скрипт, описывающий структуру БД. Этот скрипт не выглядит как исходник для поддержания структуры БД, однако, как это не парадоксально, таковым является, подробности в документации к уже упомянутому проекту. Это также может быть миграционный скрипт в любой системе контроля версии базы данных.

create table geo.Strana (    id int    , naimenovaniye varchar(255)    , primary key (id));create table geo.Gorod (    id int    , naimenovaniye varchar(255)    , strana_id int    , constraint strana_gorod foreign key (strana_id)        references geo.Strana(id));

Применим скрипт к базе данных и воспользуемся двумя инструментами СУБД (пример приведён для PostgreSQL): динамическими представлениями для извлечения сведений о структуре и возможностью создавать JSON-файлы на основе результатов сохранения запросов.

drop table if exists fk;select x.table_schema as table_schema    , x.table_name    , y.table_schema as foreign_table_schema    , y.table_name as foreign_table_nameinto temp fkfrom information_schema.referential_constraints rcjoin information_schema.key_column_usage x    on x.constraint_name = rc.constraint_namejoin information_schema.key_column_usage y    on y.ordinal_position = x.position_in_unique_constraint    and y.constraint_name = rc.unique_constraint_name;

select    json_agg(json_build_object(        'name', t.table_schema || '.' || t.table_name        , 'columns'        , (select            json_agg(json_build_object (                'name', column_name                ,'type', data_type            ))            from information_schema.columns as c            where c.table_name = t.table_name and c.table_schema = t.table_schema          )        , 'fk'        , (select            json_agg(json_build_object (                'fk_table'                , fk.foreign_table_schema || '.' || fk.foreign_table_name            ))           from fk           where fk.table_name = t.table_name and fk.table_schema = t.table_schema          )    ))from information_schema.tables as twhere table_schema = 'geo';

В результате получим JSON-файл:

[{        "name": "geo.Strana",        "columns": [{                "name": "id",                "type": "integer"            }, {                "name": "naimenovaniye",                "type": "character varying"            }        ],        "fk": null    }, {        "name": "geo.Gorod",        "columns": [{                "name": "id",                "type": "integer"            }, {                "name": "naimenovaniye",                "type": "character varying"            }, {                "name": "strana_id",                "type": "integer"            }        ],        "fk": [{                "fk_table": "geo.Strana"            }        ]    }]

В следующем разделе будет показано, как этот файл превратить в документ.

Использование шаблонизаторов

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

Формат этих правил достаточно простой, они безопасны с точки зрения исполнения, поэтому часто шаблонизаторы используются для настройки различных аспектов работы приложений непосредственно пользователями.

Самым известным языком обработки шаблонов (но далеко не самым простым) является XSLT. Самым минималистичнымMustache.

Свой язык написания шаблонов и шаблонизатор также создать довольно просто. Например, для создания системы генерации отчётов в форматах Excel и ods мы пошли этим путём.

Можно вообще обойтись без шаблонизатора, просто структурировать код определенным образом, в этой старой статье 2003 года Мартин Фаулер признается в нелюбви к XSLT и заодно объясняет, как его заменить кодом, написанным на языке Ruby. За 18 лет оказалось, что и статические языки также можно прекрасно использовать для этих целей, и XSLT прекрасно себя чувствует, и предложенный в статье подход оказался очень хорош.

В примерах будет использоваться Liquid для работы с JSON и XSLT для работы с XML. В обоих случаях будет использоваться реализация в Ruby, потому что (1) Наиболее распространенный в настоящий момент процессор AsciidocAsciidoctorнаписан на Ruby (2) Ruby-скрипты отлично работают в java и javascript, что часто позволяет не плодить цирк технологий.

Пример генерации документа из JSON-файла

Рассмотрим простой пример по генерации документа на основе полученного выше JSON-файла.

Генерация диаграммы в формате PlantUML:

{% assign bl = "\n" %}{%- for table in data -%}    class {{ table.name }}{{ bl }}    {%- for fk in table.fk -%}        {{ table.name }} "*" -- "1" {{ fk.fk_table }}{{ bl }}    {%- endfor -%}{%- endfor -%}

В примере шаблонизатор обходит все узлы, определяющие таблицы. Для каждой таблицы создается строка PlantUML для отрисовки классов class [Наименование класса]. Далее внутри каждой таблицы проверяется наличие внешних ключей и создается соединительная линия с соответствующими классами.

На выходе получаем следующий текст диаграммы:

class geo.Stranaclass geo.Gorodgeo.Gorod "*" -- "1" geo.Strana

Аналогично сгенерируем документ в формате Asciidoc:

{% assign bl = "\n" %}{% assign bbl = "\n\n" %}{%- for table in data -%}    [[{{ table.name }}]]{{- bl -}}    .Таблица {{ table.name }}{{- bl -}}    [cols="1,3,3", options="header"]{{- bl -}}    |==={{- bl -}}    | |Наименование поля |Тип поля{{ bl }}    {%- for column in table.columns -%}        |{counter:{{ table.name }}} |{{ column.name }} |{{ column.type }}{{- bl -}}    {%- endfor -%}    {%- if table.fk -%}        3+a|Определены внешние ключи на следующие таблицы:{{- bbl -}}        {%- for fk in table.fk -%}            * <<{{fk.fk_table}}, {{fk.fk_table}}>>{{- bl -}}        {%- endfor -%}    {%- endif -%}    |==={{- bbl -}}{%- endfor -%}

Для объединения обоих кусков в один документ воспользуемся директивой include:

= Структура БД:lang: ru:figure-caption: Рисунок:xrefstyle: short:sectnums:== Общая структураСтруктура базы данных изображена на рисунке (<<struktura>>).[[struktura]].Структура БД[plantuml, struktura, png, fitrect="170x240mm", srcdpi=300, width="50%"]....skinparam dpi 300left to right directioninclude::pu_sql.pu[]....== Описание таблицinclude::adoc_sql.adoc[]

Синтаксис Asciidoc рассмотрен в статье Asciidoc для ЕСКД. Подробнее структурирование документации в Asciidoc планирую описать в отдельной статье. Здесь лишь хотелось бы отметить, что при вставке диаграммы мы указываем параметры её отображения. В разных документах одну и ту же диаграмму мы можем отобразить по-разному (в разных цветах, с разным разрешением, в разной ориентации и т.п.).

Результаты превращаем в файл в формате Microsoft Word с помощью проекта, о котором рассказано в предыдущей статье.

Ключевые техники, используемые при генерации документации

Для рассмотрения ключевых техник приведём пример с преобразованием XML-файла.

Для примера возьмем выписку из ЕГРЮЛ от Федеральной налоговой службы. Не совсем документация, но удобно для демонстрации основных приёмов преобразования структурированных данных в документацию.

Исходные данные (схема xsd и пример сообщения) взяты на сайте СМЭВ 3https://smev3.gosuslugi.ru/portal/inquirytype_one.jsp?id=41108&zone=fed. Для примера приведём небольшую часть выписки из ЕГРЮЛ:

<ns1:СвНаимЮЛ НаимЮЛПолн="НАИМЕНОВАНИЕ 5087746429843"    НаимЮЛСокр="СОКРАЩЕННОЕ НАИМЕНОВАНИЕ 5087746429843">  <ns1:ГРНДата ГРН="5087746429843" ДатаЗаписи="2008-11-18"/></ns1:СвНаимЮЛ><ns1:СвАдресЮЛ>  <ns1:АдресРФ КодРегион="77" КодАдрКладр="770000000002990" Дом="7"      Корпус="6">    <fnst:Регион ТипРегион="ГОРОД" НаимРегион="МОСКВА"/>    <fnst:Улица ТипУлица="УЛИЦА" НаимУлица="ФИЛЕВСКАЯ 2-Я"/>    <fnst:ГРНДата ГРН="5087746429843" ДатаЗаписи="2008-11-18"/>  </ns1:АдресРФ></ns1:СвАдресЮЛ>

Как видно, названия тэгов и атрибутов вполне говорящие, но мы возьмем полные названия параметров из схемы xsd.

Преобразование выписки из ЕГРЮЛ в формат Asciidoc выглядит следующим образом:

<stylesheet version="1.0" xmlns="http://personeltest.ru/away/www.w3.org/1999/XSL/Transform"            xmlns:ep="uri:asciidoc:doc:automation"            extension-element-prefixes="ep">    <output method="text" /><strip-space elements="*"/>    <template match="/"><apply-templates/></template>    <template match="*[count(@*|*) > 0 and count(ancestor::*) > 0]">        <value-of select="'\n='"/>        <for-each select="ancestor::*"><value-of select="'='"/></for-each>        <value-of select="' '"/>        <value-of select="concat('{',local-name(),'}')"/><text>\n\n</text>        <text>|===\n</text>        <for-each select="(@*)|(*[./text()])">            <text>|</text><value-of select="concat('{',local-name(),'}')"/>            <text>|</text><value-of select="ep:iformat(current())"/>            <text>\n</text>        </for-each>        <text>|===\n</text>        <apply-templates/>    </template>    <template match="text()"/></stylesheet>

В примере шаблонизатор обходит все узлы файла с данными ЕГРЮЛ. Тэги, в которых есть атрибуты или дополнительные тэги трансформируются в заголовок с нужным уровнем иерархии. Атрибуты и текстовые тэгив строки таблицы. Обратите внимание, что в Asciidoc реализован очень компактный способ задания ячейки таблицы через символ |.

Наименования тэгов и атрибутов XML-документа обёрнуты в фигурные скобкиспециальный синтаксис для отображения значений атрибутов Asciidoc. Значения атрибутов легко извлекаем из xsd-схемы с помощью следующего преобразования:

<?xml version="1.0" encoding="UTF-8"?><stylesheet version="1.0" xmlns="http://personeltest.ru/away/www.w3.org/1999/XSL/Transform"            xmlns:xs="http://personeltest.ru/away/www.w3.org/2001/XMLSchema">    <output method="text" />    <strip-space elements="*"/>    <template match="*[@name]">        <value-of select="concat(':', @name, ': ')"/>        <value-of select="normalize-space(xs:annotation/xs:documentation)"/>        <text>\n</text>        <apply-templates/>    </template>    <template match="*[not(@name)]">        <apply-templates/>    </template>    <template match="text()"></template></stylesheet>

Объединим полученные значения атрибутов Asciidoc (два файла, т.к. описание сервиса по выдаче ЕГРЮЛ состоит из двух схем xsd) и файл с содержанием выписки:

:sectnums:include::adoc_egrul_xsd.adoc[]include::adoc_egrul_xsd2.adoc[]include::adoc_egrul.adoc[]

На выходе Microsoft Word даёт следующую картинку:

Борьба с пробельными символами

Поскольку конечным форматом преобразования является текстовая разметка, вопрос пробелов крайне важен: текст, смещенный на несколько пробелов, может быть воспринят как блок с моноширинным текстом.

Пробелы могут влиять на эстетику, читаемость и обрабатываемость выходного документа. Например, после каждого абзаца в Asciidoc должно быть два переноса строки. Их может быть и три, но читается файл хуже. Во многих автоматически сгенерированных документах количество переносов строк абсолютно не предсказуемо. Особенно это неудобно при сравнении версий файла. При наличии на выходе файла в формате XML или JSON можно было бы применить утилиты, создающие красивый выходной файл. Для текстовых маркапов, насколько я знаю, таких утилит не существует.

С другой стороны, крайне важно, чтобы сам шаблон был красивым и удобным для чтения и редактирования, чтобы, как минимум, были отступы в циклах и условных операторах.

Поработав со многими шаблонизаторами, пришёл к выводу, что единственный практически универсальный вариантуказать шаблонизатору, чтобы он вырезал все пробелы и переносы, а переносы указывать вручную в шаблоне. В приведенном примере есть опция <strip-space elements="*"/> и после каждой выводимой строчки помещена команда <text>\n</text>. Некоторые шаблонизаторы воспринимают \n как символ переноса. Если нет, необходимо провести пост-обработку выходного файла и самостоятельно заменять данную комбинацию на перенос строки.

В примере для Liquid применен аналогичный подход, только для наглядности символ переноса присвоен переменной bl.

Рекурсия

Рекурсия обеспечивает наглядный способ обхода узлов структурированного документа с большим количеством единообразных уровней иерархии, как в приведённой выписке из ЕГРЮЛ.

Рекурсию поддерживает большинство шаблонизаторов. Например, XSLT поддерживает рекурсию директивой apply-templates. В примере основной шаблон (template) обеспечивает обработку иерархического узла выписки из ЕГРЮЛ и далее вызывает себя для каждого узла ниже по иерархии.

Экранирование и другие операции со вставляемыми данными

Данные для вставки в Asciidoc файл могут вступить в конфликт с разметкой Asciidoc. Например, вы хотите взять текст из Open API спецификации и добавить символ ;. Однако разработчик мог при описании сам поставить тот же символ. В результате в выходной файл попадёт два символа ;; и Asciidoc будет воспринимать текст как терминологический список, и хорошо ещё, если мы быстро поймём, почему на выходе текст отформатирован странно.

Чтобы этого избежать, можно оборачивать вставляемый текст собственными функциями, которые экранируют и производят требуемые преобразования значений. В примереэто функция iformat. Она добавляет в начале и в конце значения символ нулевого пробела (zero space) и переводит значения типа даты в формат DD.MM.YYYY.

AsciidocDocAutomation = Class.new do  def iformat(node)    value = node.to_s    re = /^([0-9]{4})-([0-9]{2})-([0-9]{2})$/    vm = value.match(re)    value = "#{vm[3]}.#{vm[2]}.#{vm[1]}" if !!(value =~ re)    "​#​"  endend

Для полного отключения синтаксиса Asciidoc во вставляемых значениях, достаточно их просто экранировать.

Выводы

• Технологии автоматической генерации документации отработаны и их могут быть эффективно использованы в ИТ-проектах любого уровня сложности.
• Язык разметки Asciidoc технологичен для применения в задачах автоматической генерации документации.

И анонс: следующая статья будет посвящена вопросам обеспечения качества документации в формате Asciidoc.