Использование AsciiDoc для управления документацией на проекте (Часть 2)

Вторая часть статьи об использовании подхода документация как код.

Первая часть —> читать

Установка и настройка

Поскольку большая часть команды использует Linux на своих рабочих станциях, примеры установки пакетов будут приведены для Ubuntu.

Установка пакетов

Установка Asciidoctor:

$ sudo apt-get install asciidoctor

Установка шрифтов, если необходимо:

$ wget https://downloads.sourceforge.net/project/mscorefonts2/rpms/msttcore-fonts-installer-2.6-1.noarch.rpm   $ sudo add-apt-repository universe  $ sudo apt-get update  $ sudo apt-get install alien  $ sudo alien msttcore-fonts-installer-2.6-1.noarch.rpm  $ sudo dpkg -i msttcore-fonts-installer-2.6-1.noarch.deb 

Использование шаблонов файла для экспорта в PDF:

$ gem install asciidoctor-pdf

Установка asciidoctor-diagram, который необходим  для поддержки работы с диаграммами:

$ gem install asciidoctor-diagram

Использование шаблонов файла для экспорта в PDF

Для конвертации файлов ADOC в PDF можно использовать собственные кастомные темы в нотации YAML. Более подробное описание можно найти здесь и здесь.

$ asciidoctor-pdf -a pdf-style=templates/NVG.Style.yml -r asciidoctor-diagram specs/general/same-system/NVG.System1.adoc

Для экспорта в PDF с учетом диаграмм (например, plantuml) необходимо установить дополнительный пакет:

$ gem install asciidoctor-diagram

Конвертация из docx в AsciiDoc 

После перехода на использование AsciiDoc нам необходимо было решить вопрос о том, что делать с документацией, написанной в формате docx. Для этого мы использовали пакет pandoc, который является универсальной утилитой для преобразования файлов из различных форматов, и perl.

$ pandoc --from=docx --to=asciidoc --wrap=none --atx-headers --extract-media=media NVG.System1.docx > NVG.System1.adoc  $ perl -W -pe  's!\[\[_.*]]!!g' -i NVG.System1.adoc  $ perl -W -pe  's!\|==*!|====!g' -i NVG.System1.adoc  $ perl -W -pe 's!(\w\w+)\.\s+(\w)!$1.\n$2!g' -i NVG.System1.adoc  $ perl -W -pe 's!^Figure (\d+)\s?(.*)![[fig-$1]]\n.$2\n!g' -i  NVG.System1.adoc  $ perl -W -pe 's!Figure (\d+)!<<fig-$1>>!g' -i NVG.System1.adoc

Возможности

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

Работа с разделами

= Смена логики работы для тарификационного номера   :author: Alexey Vasiliev, Doronin Alexander   :email: vasiliev@domain.ru, doronin@doamin.ru   :revnumber: v1.0   :revdate: 25.01.2022   :revremark: Draft   :keywords: Техническое задание   :encoding: utf-8    :lang: ru    :sectnums:    :toc:    :sectnumlevels: 7    :toc-title: Оглавление    :legacy-footnoteref:    :figure-caption: рис.    :imagesdir: ./media    :source-highlighter: rouge    :includedir: ../../../../templates 

Здесь:

• = — используется для заголовка документа;

• :author: — авторы;

• :email: — адреса электронной почты;

• :revnumber: — номер версии документа, который должен содержать как минимум один цифровой символ;

• :revdate: — дата завершения работы над версией документа;

• :revremark: — информация о данной версии документа, например, черновик;

• :keywords: — ключевые слова;

• :encoding: utf-8 — кодировка документа;

• :lang: ru — язык документа;

• :toc: — разрешить оглавление;

• :toc-title: Оглавление — название для оглавления;

• :figure-caption: рис. — автоматическое добавление метки рис. для всех изображений, используемых в документе;

• :imagesdir: ./media — путь к папке, где находятся изображения;

• :includedir: ../../../../templates — путь к папке, где лежат шаблоны, если они используются в документе. Например, общая для всех документов шапка. В документе добавляется командой include::{includedir}/header-TZ.adoc[].

Разделы

= Смена логики работы для тарификационного номера == Термины и определения == Техническая реализация === Архитектура решения === Работа с сервисами ==== Группы обзвона ==== Очередь

Результат

Форматирование текста

*Жирный*  **Т**олько одна буква  _Курсив_

Результат:

Жирный

Только одна буква

Курсив

Списки

Ненумерованные списки

* 1-ый уровень ** 2-ой уровень *** 3-ий уровень **** 4-ый уровень ***** 5-ий уровень * Снова первый уровень

Результат:

• 1-ый уровень

  • 2-ой уровень

    • 3-ий уровень

      • 4-ый уровень

        • 5-ий уровень

• Снова первый уровень

Нумерованные списки

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

[start=2] . Смена логики работы . Провижининг настроек . Проверка

Результат:

2. Смена логики работы

3. Провижининг настроек

4. Проверка

Работа с таблицами

Работа с таблицами и возможность форматировать текст в таблицах стали одной из причин выбора для работы с документами AsciiDoc.

[width="100%",options="header", cols="<,^,>"] |==================== |Элемент |Тип, Размерность |Сорт. |Описание |Ручная настройка  |Столбец таблицы, да/нет  |Да  |В данном столбце отображается, сопоставлялся ли пользователь CRM абоненту ВАТС вручную, или был автоматически подобран с помощью автоматической синхронизации.  |Ручная настройка (ссылка)  |Ссылка  |Нет  |При нажатии на ссылку сортирует список по признаку ручной настройки соответствия абонентов ВАТС и пользователей CRM – сначала настроенные вручную (значение «Да»). При повторном нажатии список сортируется в обратном порядке  |Отображать a |Выпадающий список Варианты:  * по 10 записей * по 25 записей * по 50 записей * по 100 записей  |Нет  |С помощью данного выпадающего списка можно выбрать количество отображаемых в списке вызовов строк. |====================

Результат

Здесь:

• width — ширина таблицы;

• options=»header» — использование заголовка;

• cols=»<,^,>» — три колонки в таблицы с форматированием: < — выравнивание по левому краю, ^ -выравнивание посередине, > — выравнивание по правому краю;

• a| — позволяет в колонке вставить любые элементы блочного уровня (абзацы, разграниченные блоки и блочные макросы). Элементы будут обработаны и отображены.

Вставка изображений

[#cn-cc] .Название изображения image::test.png[100%,align="center"]

Результат

Здесь

• [#cn-cc] — ссылка на изображение. В тексте можно использовать <<cn-cc>>

• .Название изображения — название изображения

• image::test.png[100%,align=»center»] — ссылка на файл в файловой системе, изображение должно быть в папке ./media

Удобные трюки AsciiDoc

Автоматическая нумерация ссылок в коде

[source,xml] ---- <?xml version="1.0" encoding="ISO-8859-1"?> <BroadsoftDocument protocol="OCI" xmlns="C" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">    <userId xmlns="">admin</userId>    <command xsi:type="UserChargeNumberModifyRequest" xmlns="">           <userId>X228AutoAttendant1</userId> <.>           <phoneNumber>89142222222</phoneNumber> <.>     <useChargeNumberForEnhancedTranslations>true</useChargeNumberForEnhancedTranslations><.>     <sendChargeNumberToNetwork>true</sendChargeNumberToNetwork> <.>    </command> </BroadsoftDocument> ---- <.> userID соответствующей сущности <.> тарификационный номер <.> всегда true <.> всегда true

Результат 

Использование блоков в списках

- Первый блок + ---- " class="formula inline"> su - ---- - Второй блок + ---- $ pwd $ /root ---- - Третий блок + ---- $ vim .bashrcы ----

Результат 

Работа с диаграммами

Для работы с диаграммами мы решили использовать PlantUML, т.к. он поддерживает работу:

• с диаграммами последовательности;

• с диаграммами активности;

• с диаграммами развертывания.

Примеры использования

Диаграмма последовательности:

[plantuml, format="png", id="vpbx-bwks"] ---- participant VPBX participant "BWKS-business" as BWKSB queue Rabbit database Redis participant "BWKS-sender" as BWKSS participant BWKS   VPBX -> BWKSB : POST Request BWKSB -> VPBX  : Result VPBX -> BWKSB : PUT Request BWKSB -> VPBX  : Result VPBX -> BWKSB : DELETE Request BWKSB -> VPBX  : Result BWKSB -> BWKSS : XML Request BWKSS -> BWKSB : XML Respone BWKSS -> Redis : Create Record Redis -> BWKSB : Get Record List BWKSS -> BWKS : Request BWKS -> BWKSS  : Respone ----  sequenceDiagram  Sys1 ->> Sys2 : POST Request Sys2 ->> Sys1  : Result Sys1 ->> Sys2 : PUT Request Sys2 ->> Sys1  : Result Sys1 ->> Sys2 : DELETE Request Sys2 ->> Sys1  : Result Sys2 ->> Sys3 : XML Request Sys3 ->> Sys2 : XML Respone Sys3 ->> Redis : Create Record Redis ->> Sys2 : Get Record List Sys3 ->> Sys4 : Request Sys4 ->> Sys3  : Respone

Результат

Итоги — что получили

• Все находится в одном репозитории. Любой член команды может внести изменения не только в исходных код, но и в документацию. Нет необходимости сначала объяснять аналитику или рассказывать о том, какие  изменения были сделаны. Также аналитик вносит исправления в документы, которые теперь видны у разработчика в его любимой IDE;

• No vendor lock-in, простое переключение между разными форматами и инструментами;

• Более тесное сотрудничество между командами и отделами;

• Унифицированные, оптимизированные рабочие процессы;

• Автоматизацию рутинных операций;

• Одновременный выпуск релизов и документации.