Создание постановки по добавлению комментариев к конвертируемым файлам в Antora

Подход, используемый для создания документации на языках разметки, как код, называется Doc as Code (документация, как код). Этот подход подразумевает создание документации, как и создание кодовой базы проекта, в репозитории – с помощью IDE, с системой контроля версий и анализом добавляемых файлов в репозиторий: автоматические проверки CI/CD и утверждение со стороны коллег.

Doc as code подразумевает использование инструментов, которые конвертируют файлы на языке разметки в статические веб-сайты. Одним из таких инструментов является Antora.

Antora работает с файлами в формате Asciidoc. Специалистам, работающим с документацией в формате кода, необходимо написать текст на языке разметки Asciidoc в репозитории, в котором настроена Antora. Затем, с помощью конфигурационных файлов в форматах YAML, JSON или TOML, Antora собирает все файлы – текст, изображения, образцы и другие вспомогательные материалы – из каждого корневого поддерева источника контента. Затем Antora создает виртуальный файл для каждого входного файла. После этого файлы AsciiDoc в репозитории преобразуются во встраиваемый HTML с помощью Asciidoctor.js. В итоге получаются сконвертированные HTML файлы на веб-странице. Эти файлы могут содержать:

• Текст;
• Картинки;
• Вложения;
• Ссылки.

Получаемая документация может быть использована аналитиками или техническими писателями для описания постановок разработчикам. Создание документации на веб-страницах удобно для хранения информации по разрабатываемому функционалу в одном месте – репозитории – однако, добавление комментариев к странице не предусмотрено Antora.

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

• текстовые поля «Автор» и «Комментарий»;
• кнопку «Сохранить».

При нажатии на кнопку «Сохранить» необходимо сделать проверку, чтобы поля «Автор» и «Комментарий» были заполнены:

• если поля не заполнены, то вывести предупреждение «Одно из полей не заполнено» и комментарий не добавляется к странице;
• если все поля заполнены, то комментарий добавляется в конец страницы.

Комментарии должны сохраняться в формате json:

{
 "author":"Александра Биненда",
 "comment":"Необходимо дополнить информацию",
 "date":"2012-04-21T18:25:43-05:00"
}

Рассмотрим пример добавления комментария на веб-странице Antora.

Добавленные поля ввода и кнопка представлены на рисунке 1.

Далее заполним одно поле и нажмем кнопку «Сохранить». Веб-страница выдаст ошибку, комментарий не будет добавлен – рисунок 2.

Рис. 1. Поля ввода комментария

Рис. 2. Ошибка сохранения комментария

Заполним поля полностью, как показано на рисунке 3. Затем нажмем кнопку «Сохранить». Добавленный комментарий отобразиться на веб-странице, как показано на рисунке 4.

Рис. 3. Заполненные поля комментария

Рис. 4. Добавленный комментарий к странице