Как писать документацию

Документация пишется в формате md, поддерживается так же формат xml. Помимо стандартных тэгов используйте кастомные тэги от Writerside

Начало работы

Клонируем репозиторий с документацией

git clone git@git.docacrm.com:doca/docs.git doca_docs

Открываем в любой удобной JetBrains IDE. И идем в настройки, а там в плагины. Нам нужно установить плагин Writerside:

Теперь перезагружаем IDE

Обновляем документацию. Может кто-то уже пушил в main

git pull

Где ее смотреть?

Вы можете обозревать документацию, выбрав в левой панели инструментов пункт Writerside

Также можно открыть ее превью на правой панели инструментов

Структура

Я рекомендую использовать обычный project-view для редактирования документации, так как Writerside не умеет в файл-мэнеджмент. Давай чутка пробежимся по структуре документации

/Build                # Папка с собраной в html документацией 
/Writerside           # Основная папка
  /cfg                # Конфиги документации
  /images             # Папка с картинками
  /topics             # Папка с документацией
    /Doca             
      /backend        # Докуменатция Doca
      /front          # Документация админки
      /medic          # Докуменатция по Яздоров
      /old_eatabox    # Документация старого eatobox
      ... md          # Прочая основная документация

А что писать?

Например: в результате работ Вы добавили поле в объект visits. Вам необходимо дополнить существующий объект или (если его еще нет) добавить сам объект с обновленным полем. Добавьте информацию о требованиях - для чего это поле предназначено, где оно используется, какие значения может принимать.

Добавьте информацию в changelog

У меня мелкая правка ее тоже писать?

Да, используй changelog. Напиши что ты изменил и в каком проекте. Например

Исправлен баг с занятостью кабинета, если график создан правилом medic!141

Новая страница/раздел

Если Вы хотите создать новую страницу, нужно создать файл с расширением .md в нужной Вам папке.

Написал документацию. Но ее нет в списке

Да. Чтобы добавить в список Вашу страницу, нужно открыть файл in.tree и добавить новый элемент куда Вам нужно

Теперь она должна появится у Вас

Написал. Как залить?

Все просто. Можно сразу пушить в main

git add .
git commit -m "Обновлена документация объекта посещение в проекте Медик"
git push

Да вот так просто. Сработает автообновление после ее обновления в git

15 мая 2025