Использование 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]
. Смена логики работы
. Провижининг настроек
. Проверка

Результат:

Смена логики работы
Провижининг настроек
Проверка

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

Работа с таблицами и возможность форматировать текст в таблицах стали одной из причин выбора для работы с документами 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, простое переключение между разными форматами и инструментами;
Более тесное сотрудничество между командами и отделами;
Унифицированные, оптимизированные рабочие процессы;
Автоматизацию рутинных операций;
Одновременный выпуск релизов и документации.

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

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

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

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

Возможности

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

Здесь:

Разделы

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

Жирный

Списки

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

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

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

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

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

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

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

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

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

Публикации

Информация