Skip to main content

Дополнение документации

Ниже представлены шаги, которые необходимо выполнить для дополнения/изменения разделов этой документации.

Движок документации

В качестве движка используется Docusaurus. Для понимания как писать документацию следует изучить:

  1. Раздел с описанием работы с Docs. Как создавать новый раздел, как описывать метаинформацию по странице.
    1. Мы используем автогенерируемое меню, так что изучите зачем нужен файл _category_.json
  2. Изучите язык разметки Markdown
  3. Изучите дополнительный фичи для разметки от Docusaurus

Внесение изменений в документацию

Есть два способа внести изменения:

  1. Через web-интерфейс Gitlab. Этот способ подходит только для мелких правок, например поправить опечатку.
  2. Через локалку. Этот способ основной и позволяет смотреть как будут выглядеть изменения.

Оба способа подразумевают, что у вас есть доступ к репозиторию с документацией https://git.greensight.ru/ensi/documentation/docs-ensi-tech

Изменение через web-интерфейс​

Ищем нужную доку тут https://git.greensight.ru/ensi/documentation/docs-ensi-tech/-/tree/master/website/docs. Переходим в режим редактирования, вносим правки, сохраняем.

Изменение через локалку​

Требования к ПО​

Для работы с документацией на локалке потребуется:

  1. Установленный git и понимание основ: как работать с ветками, коммитить и пушить изменения;
  2. Любой текстовый редактор, который вам будет удобен. Это может быть любой блокнот, как Notepad++ или Sublime, а может быть и Visual Studio Code или любая IDE, которая сможет подсвечивать разметку файлов;
  3. Установленный nodejs версии 16.14 и выше

Первичная установка​

Первым делом нужно склонировать репозиторий и установить зависимости:

git clone git@git.greensight.ru:ensi/documentation/docs-ensi-tech.git
cd docs-ensi-tech/website
npm install

Процесс внесения изменений​

Запускаем локально сервис документации:

npm start

После этого документация должна быть доступна по адресу http://localhost:3000

Вносим изменения в .mdx файлы документации, проверяем что в браузере всё соответствует нашим ожиданиям.

После этого дублируем изменения в директорию i18n/en/docusaurus-plugin-content-docs/current. Перезапускаем команду с новой локалью:

npm run start -- --locale en

и проверяем что всё ок.

В самом конце выполняем последовательно 2 команды и проверяем что переключение между версиями сайта работает корректно

npm run build
npm run serve

Для сохранения работы её нужно закоммитить и запушить в Gitlab. Для этого переходим в корневую папку с репозиторием и выполняем:

git checkout -b <ключ_задачи> # Название ветки следует указывать в нижнем регистре, например ef-123
git add -A
git commit -m "<ключ_задач> <какое-то ваше сообщение об изменении в документации>" # Например "EF-123 add products"
git push -u origin <ключ_задачи>

Далее необходимо создать MR. Заходим на страницу https://git.greensight.ru/ensi/documentation/docs-ensi-tech/-/merge_requests/new и выбираем в качестве исходной ветви вашу

Оформляем MR в соответствии с Code Review Guide:

  • пишем в заголовок код_задачи_из_трекера краткое_описание
  • назначаем Assignee (вы сами)
  • назначаем Reviewer (тот, кто должен проверить ваш MR)

После создания, отправляем ссылку на MR через телеграмм ревьюиру. Покажите MR также Техлиду Ensi

После получения аппрува необходимо смержить MR (для этого есть отдельная кнопка в интерфейсе), после этого система автоматически отгрузит правки на боевой домен.