Інструменти розробки технічної документації

Опис інструментів для розробки технічної документації проекту

Розробка документації ведеться:

  • на мові AsciiDoc (мова розмітки з підтримкою структурних та семантичних елементів, яка використовується для формування текстових документів)

  • за допомогою PlantUml (інструмент з відкритим кодом, який дозволяє описувати UML діаграми, візуалізувати JSON та YAML у текстовому вигляді за допомогою власного доменного синтаксису)

  • та за допомогою Draw.IO (онлайн інструмент створення діаграм різних типів з можливостями збереження у SVG форматі с підтримкою подальшого редагування, можна використовувати будь-який інший svg-редактор)

Для структурування текстових AsciiDoc документів за розділами та формування єдиного статичного HTML сайту з технічною документацією на базі .yml плейбука конфігурації використовується Antora

Офіційна документація інструментів

Локальне оточення для розробки технічної документації

Для ведення розробки документації, необхідно встановити:

  • IntelliJ IDEA / JetBrains WebStorm — інтегроване середовище розробки

  • AsciiDoc JetBrains плагін — підтримка синтаксису AsciiDoc та попереднього перегляду в IntelliJ IDEA та WebStorm

  • PlantUML Integration IntelliJ IDEA плагін — плагін для розробки діаграм у текстовому вигляді з використанням PlantUML синтаксису та їх попереднього перегляду

  • (опційно) Asciidoctor.js Live Preview — розширення до браузера Chrome для перегляду AsciiDoc документів (файли з розширенням .adoc)

Перегляд технічної документації через вбудовані можливості перегляду IntelliJ IDEA

Для перегляду згенерованої документації на локальному оточенні можна використовувати вбудовані можливості перегляду IntelliJ IDEA (File > Open In > Browser > Built-in Preview)

Локальне будування Antora

Також можна збудувати загальну структуру документації ddm-architecture за допомогою Antora у локальному оточенні та відкрити збудований файл index.html браузером, встановленим за замовчуванням

Встановлення Antora

Повна інструкція встановлення Antora тут

Щоб перевірити чи встановлена Antora можна виконати

antora -v

Для встановлення Antora потрібно для початку встановити Node або yarn

Щоб перевірити чи Node встановлений та якої версії можна виконати

node --version

Встановлення Node на Linux

Для встановлення Node на Linux треба виконати

nvm install --lts

Якщо у вас нема встановленого nvm, то його можна встановити за інструкцією

Повна інструкція по встановленню Node на Linux тут

Користувачі Linux ласкаво просимо додати важливих деталей які не вказані в цій або повній інструкції

Встановлення Node на macOS

Для встановлення Node на macOS треба виконати

nvm install --lts

Якщо у вас нема встановленого nvm, то його можна встановити за інструкцією

Повна інструкція по встановленню Node на macOS тут

Користувачі macOS ласкаво просимо додати важливих деталей які не вказані в цій або повній інструкції

Встановлення Node на Windows

Для встановлення Node на Windows треба:

  • Встановити Chocolatey

    • Відкрити PowerShell від імені адміністратора

    • Виконати:

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

  • Встановити nvm:

    • Відкрити PowerShell від імені адміністратора (можна в тому ж вікні що й для встановлення Chocolatey)

    • Виконати:

choco install -y nvm

  • Встановити node:

    • Відкрити нове вікно PowerShell

    • Виконати:

nvm install 16.1.0
Для Windows треба вказувати точну версію Node (приклад - 16.0.1) доки не вирішено nvm-windows#214

Якщо після nvm install у вас нема встановленого Node, то можна спробувати встановити Node через Chocolatey choco install nodejs-lts або choco install nodejs

Повна інструкція по встановленню Node на Windows тут

Користувачі Windows ласкаво просимо додати важливих деталей які не вказані в цій або повній інструкції

Встановлення Antora за допомогою npm

Щоб встановити Antora за допомогою npm треба виконати:

npm i -g @antora/cli@2.3 @antora/site-generator-default@2.3

Встановлення Antora за допомогою yarn

Щоб встановити Antora за допомогою yarn треба виконати:

yarn global add @antora/cli@2.3

yarn global add @antora/site-generator-default@2.3

Надання Antora доступу у віддалені Git репозиторії

Щоб надати доступ Antora до репозиторіів треба:

  • Виконати:

git config --global credential.helper store && \
  echo -n 'Repository URL: ' && read REPLY && \
  git ls-remote -h $REPLY > /dev/null

  • Вписати URL Git репозиторію до якого треба надати доступ (та повторити для кожного репозиторію із site.yml)

Також можна використати токени особистого доступу:

  • Зайти до GitLab personal access token

  • Створити токен зі скоупом read_repository

  • Та надати доступ до репозиторіїв:

    • Через змінну оточення GIT_CREDENTIALS зі значенням https://<FirstName_LastName>:<personalAccessToken>@gitbud.epam.com (Antora буде використовувати цей токен для всіх репозиторіїв у https://gitbud.epam.com)

    • Через файл .git_credentials на базі файлу шаблону .git-credentials.local шляхом копіювання та видалення суфіксу .local та додання необхідних репозиторіїв у вигляді:

https://<personalAccessToken>:@gitbud.epam.com/<repository_path>
# aбо
https://<FirstName_LastName>:<personalAccessToken>@gitbud.epam.com/<repository_path>
# aбо один токен на всі репозиторії
https://<FirstName_LastName>:<personalAccessToken>@gitbud.epam.com/
Повна інструкція надання доступу до приватних репозиторіїв знаходиться тут

Генерація технічної документації

Для генерації статичного HTML сайту документації з використанням останніх версій розділів з відповідних репозиторіїв треба виконати:

antora site.yml

Для генерації статичного HTML сайту документації з використанням локальних копій розділів документації (необхідно створити з файлу site-template.yml файл site-local.yml та відкорегувати шляхи до локальних директорій. site-local.yml знаходиться у .gitignore):

antora site-local.yml

В обох випадках, сайт технічної документації буде згенеровано у директорію, налаштовану у .yml плейбуці:

output:
  dir: ./build/site

Проглянути збудований сайт можна через браузер, встановлений за замовчуванням, шляхом відкриття файлу ./build/site/index.html в IntelliJ IDEA (File > Open In > Browser > Default)

Налаштування швидкого запуску процесу генерації документації в IntelliJ IDEA

Для автоматизації кроку генерації документації, в IntelliJ IDEA можно налаштувати конфігурацію запуску Shell Script:

  • Викликати з головного меню: Run > Edit Configurations > Add New Configuration

  • Вибрати тип конфігурації запуску Shell Script

  • Вказати ім’я Name: antora-site

  • Вказати тип скрипта Execute: Shell Script

  • Вказати скрипт Script text: antora site-local.yml

Як результат, в IntelliJ IDEA з’явиться додаткова конфігурація запуску для генерації технічної документації через Antora antora-site, яку можна використовувати у якості швидкого виклику.