Вступление
Файл с расширением ADOC - это AsciiDoc файл, текстовый документ, использующий формат AsciiDoc для разметки. AsciiDoc похож на Markdown и предназначен для создания документации, статей, книг и других типов документов. Он поддерживает различные элементы форматирования, такие как заголовки, списки, ссылки, изображения, таблицы и математические формулы.
Этот формат очень удобен для совместного оформления документации для ПО. Он содержит описание текста, таблиц и форматирования при момощи ascii символов, что позволяет легко его интегрировать с git
Для публичного просмотра, можно генерить pdf файлы, это можно делать в ручную или использовать методы CI/CD. Рассмотрим способ ручной сборки.
Установка Docker
Добавляем текущего пользователя в группу docker
sudo usermod -aG docker $USER
Применяем изменения (может потребоваться перезагрузка или выход из сеанса)
newgrp docker
Проверяем
groups
Установка Asciidoctor
Asciidoctor - это текстовый процессор и набор инструментов для публикации, который преобразует разметку AsciiDoc в различные форматы, включая HTML, PDF, DocBook и другие
Скачиваем официальный образ Asciidoctor
$ sudo docker pull asciidoctor/docker-asciidoctor
# Проверяем
$ docker images | grep asciidoctor
asciidoctor/docker-asciidoctor latest c651f1c01e9a 3 days ago 1.36GB
Структура каталога с проектом ADOC
Для удобства можно делить документ на отдельные страницы, по форматированию я сделаю отдельную статью
Но общая структура примерно такая, скриншоты и иллюстрации хранятся в отдельной папке и их удобно передавать техническому писателю.
Запуск сборки.
sudo docker run --rm -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf ./3dserver-admin-manual.adoc -o outbox/3dserver-admin-manual-v1.0.2.pdf
В результате сборки получаем в папке output, файл с 3dserver-admin-manual-v1.0.2.pdf
Итоговый pdf нам не нужен в репозитории, поэтому в .gitignore добавим строчку:
**/outbox/*
Редактирование ADoc
В программе VSCode есть плагин, который позволяем просматривать форматирование AsciiDoc.
инструкция к плагину к плагину
Для установки под Astra Linux я использую скрипт, т.к. в AstraLinux 1.7 не хватало одной зависимости для запуска.
git clone https://gitflic.ru/project/litvinov_mv/astra-linux-vscode.git
cd astra-linux-vscode/
bash install-vscode.sh
Подключение AsciiDoc плагина
В среде VSCode нажимаем:
Ctrl + P
ext install asciidoctor.asciidoctor-vscode
[install] plugin
Для просмотра preview ADOC используем сочетание клавиш:
Ctrl+Shift+V - preview