Главная
АИ #18 (200)
Статьи журнала АИ #18 (200)
Создание постановки по добавлению комментариев к конвертируемым файлам в Antora

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

Автор(-ы):

Биненда Александра Дмитриевна

2 мая 2024

Секция

Информационные технологии

Ключевые слова

Antora
комментарии
конвертируемые файлы
Doc as Code

Аннотация статьи

В работе рассматривается инструмент по работе с подходом Doc as Code – Antora. Приводится описание данного инструмента. Также представлена постановка по добавлению комментариев к конвертируемым файлам в Antora: необходимые поля для добавления, кнопка, проверка заполнения полей, пример json-файла, в котором будут храниться комментарии к документации. Представлен пример сконвертированной страницы с добавленным комментарием.

Текст статьи

Подход, используемый для создания документации на языках разметки, как код, называется 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.

image.png

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

image.png

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

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

image.png

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

image.png

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

Список литературы

  1. Documentation As Code / Ralf D. Müller and Gernot Starke [Электронный ресурс]. – URL: https://docsascode.org/ (дата обращения: 26.04.2024).
  2. Antora / [Электронный ресурс]. – URL: https://antora.org/ (дата обращения: 02.05.2024).
  3. JSON / [Электронный ресурс]. – URL: https://ru.wikipedia.org/wiki/JSON (дата обращения: 02.05.2024).

Поделиться

191

Биненда А. Д. Создание постановки по добавлению комментариев к конвертируемым файлам в Antora // Актуальные исследования. 2024. №18 (200). Ч.I.С. 28-31. URL: https://apni.ru/article/9140-sozdanie-postanovki-po-dobavleniyu-kommentariev-k-konvertiruemym-fajlam-v-antora

Похожие статьи

Другие статьи из раздела «Информационные технологии»

Все статьи выпуска
Актуальные исследования

#25 (207)

Прием материалов

15 июня - 21 июня

осталось 4 дня

Размещение PDF-версии журнала

26 июня

Размещение электронной версии статьи

сразу после оплаты

Рассылка печатных экземпляров

5 июля