Автор(-ы):
Биненда Александра Дмитриевна
2 мая 2024
Секция
Информационные технологии
Ключевые слова
Аннотация статьи
В работе рассматривается инструмент по работе с подходом 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.
Рис. 1. Поля ввода комментария
Рис. 2. Ошибка сохранения комментария
Заполним поля полностью, как показано на рисунке 3. Затем нажмем кнопку «Сохранить». Добавленный комментарий отобразиться на веб-странице, как показано на рисунке 4.
Рис. 3. Заполненные поля комментария
Рис. 4. Добавленный комментарий к странице
Список литературы
Поделиться
Биненда А. Д. Создание постановки по добавлению комментариев к конвертируемым файлам в Antora // Актуальные исследования. 2024. №18 (200). Ч.I.С. 28-31. URL: https://apni.ru/article/9140-sozdanie-postanovki-po-dobavleniyu-kommentariev-k-konvertiruemym-fajlam-v-antora