Использование 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!(ww+).s+(w)!$1.n$2!g' -i NVG.System1.adoc

$ perl -W -pe 's!^Figure (d+)s?(.*)![[fig-$1]]n.$2n!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, простое переключение между разными форматами и инструментами;

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

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

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

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