Работа со справочной документацией

Справочная документация - для Веб-ЛИМС "Тритея" представляет собой связанный набор HTML-страниц, размещенных по ссылкам:

• https://triteia.chemsoft.ru/doc
• https://astra.chemsoft.ru/doc

Этапы документирования Веб-ЛИМС

1. Настройка локального рабочего окружения
2. Формирование и актуализация Markdown-исходников документации
3. Фиксация изменений и отправка в удаленный репозиторий GitLab
4. Проверка и утверждение изменений в Merge Request
5. Автоматическая генерация HTML-страниц и обновление сайта

Настройка локального рабочего окружения

Для создания, редактирования и публикации документов вам потребуется любой текстовый редактор или среда разработки (IDE) с поддержкой формата Markdown и встроенной системой контроля версий Git.

Вы можете использовать привычный для себя инструмент (например, WebStorm, Obsidian, Sublime Text).

Если у вас нет предпочтений, рекомендуется использовать Visual Studio Code — бесплатный кроссплатформенный редактор, в котором по умолчанию есть все необходимые инструменты для работы.

Скачать дистрибутив: https://code.visualstudio.com/

Visual Studio Code

1.1.1 Начало работы и общие сведения Слева в верхней части интерфейса находятся вкладки, необходимые для работы. Для документирования понадобятся:

Проводник Система управления версиями Расширения

Для начала работы открыть директорию с проектом выполнив действия:

Выбрать файл в верхнем левом углу В появившемся меню нажать Открыть папку... Найти и выбрать папку с документацией, предварительно скачанной из gitlab

Во вкладке Проводник сверху появится строка с названием папки. Чтобы работать с её содержимым, развернуть, нажав на её название

Развёрнутая папка проекта:

Чтобы создать файл или папку необходимо выделить директорию и нажать на кнопку Создать файл... или Создать папку:

Содержимое открытых файлов отображается в правой части интерфейса VSCode. Для файлов расширения markdown (.md) по умолчанию предусмотрен предпросмотр (кнопка Открыть область предварительного просмотра справа в верхнем правом углу):

Выбрать действие над файлом или папкой можно вызвав контекстное меню, нажатием ПКМ:

1.1.2 установка русского языка для интерфейса VSCode ввести команду: Ctrl + Shift + P, в верху экрана посередине появится поле ввода команд

ввести команду Configure Display Language и нажимаем Enter

ввести русский и нажать Enter

Нажимаем restart, тем самым перезапуская Visual Studio Code и применяя русский интерфейс к программе:

1.1.3 Расширения: 1.1.3.1 Russian - Code Spell Checker Автоматически проверяет орфографию

Установка расширения:

перейти во вкладку "Расширения" ввести в поиск Russian - Code Spell Checker нажать синюю кнопку install

После установки нажать F1 (появится поле ввода вверху экрана) и ввести в поле:

Enable Russian Spell Checker Dictionary, нажать Enter

Disable Russian Spell Checker Dictionary in Workspace, нажать Enter

Настройка завершена !

1.1.3.2 EasyMarkdown Добавляет некоторые функции в интерфейс VSCode для быстрого редактирования markdown:

Добавленные функции:

Система контроля версий GIT

Для установки модулей и настройки авторизации в GitLab необходимо воспользоваться помощью программиста.

Формирование и актуализация Markdown-исходников документации

Формирование структуры и содержимого документации, путём создания (редактирования) файлов расширения markdown, являющегося отдельным документом с соответствующего определённой главе или подразделу, распределение .md файлов в файловой структуре согласно иерархии

2.1 Создание оглавления Файл SUMMARY.md необходим для формирования заголовков документации, их последовательности и иерархии. Файл является неотъемлемой частью документации и должен находиться только в корне проекта.

Форматирование файла-оглавления должно осуществляться согласно правилам, описанным ниже. Любое отклонение от правил форматирования приведёт к игнорированию внесённых изменений или может вызвать ошибку при создании структуры документа.

Оглавление, описанное в SUMMARY.md состоит из элементов, каждый из которых определяет то, какой будет структура оглавления и каким будет контент каждой главы в итоговом документе

2.1.1 Элементы оглавления в SUMMARY.md Пример оглавления в SUMMARY.md может выглядеть следующим образом:

[Общая информация]()

1. Глава 1

- [Назначение и общие сведения]()

   - [Общие приёмы работы]()
   - [Общий порядок работы]()

---

1. Глава 2

- [Описание работы и синтаксиса скриптов]()

 - [Типы данных](Описание_работы_и_синтаксиса_скриптов/1.Типы_данных/1.Типы_данных.md)
 - [Операторы](Описание_работы_и_синтаксиса_скриптов/2.Операторы/2.Операторы.md)
 - [Переменные](Описание_работы_и_синтаксиса_скриптов/3.Переменные/3.Переменные.md)
 - [Функции и методы](Описание_работы_и_синтаксиса_скриптов/4.Функции_и_методы/4.Функции_и_методы.md)
 - [Синтаксические конструкции](Описание_работы_и_синтаксиса_скриптов/5.Синтаксические_конструкции/5.Синтаксические_конструкциию.md)
 - [Примеры и комментарии](Описание_работы_и_синтаксиса_скриптов/6.Примеры/6.Примеры.md)

[Инструкция mdBook](readme.md) Страница с документацией с данным оглавлением будет иметь следующий вид:

18

Основной структурной единицей оглавления являются ссылки Ссылки состоят из:

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

Элементы, которые используются при создании оглавлений:

Ненумерованные главы

Ненумерованный заголовок первого уровня

Нумерованный заголовок

Глава-черновик

Разделитель

2.1.1.1 Ненумерованные главы В SUMMARY.md таким главам соответствует ссылка без знака - и табуляции

2.1.1.1.1 Префиксная глава Префиксная глава — добавляется перед основными пронумерованными главами. Такие главы не будут пронумерованы. Это полезно для предисловий, вступлений и т. д. На такие главы существуют ограничения:

префиксные главы не могут быть вложенными; все они должны быть на корневом уровне. не получится добавить префиксные главы после добавления пронумерованных глав. 2.1.1.1.2 Суффиксная глава Как и главы-префиксы, главы-суффиксы не нумеруются, но следуют после пронумерованных глав

2.1.1.2 Ненумерованный заголовок первого уровня В SUMMARY.md таким заголовкам соответствует текст с одним знаком # в начале.

Заголовки уровня 1 можно использовать в качестве заголовка для следующих пронумерованных глав. Это можно использовать для логического разделения различных разделов документа. Заголовок отображается как некликабельный текст. Заголовки необязательны, а пронумерованные главы можно разбить на столько частей, сколько необходимо. Заголовки частей должны быть заголовками h1 (один #), другие уровни заголовков игнорируются.

2.1.1.3 Нумерованный заголовок В SUMMARY.md таким главам соответствует ссылка со знаком -

Нумерованные главы описывают основное содержание документа и могут быть вложенными, что позволяет создать необходимую иерархию (главы, подглавы и т. д.). Чтобы сделать нумерованную главу вложенной, к ссылке в начале добавляется табуляция

2.1.1.4 Глава-черновик В SUMMARY.md таким главам соответствует ссылка с пустым путём к файлу с описанием

Главы-черновики - это главы без файла и, следовательно, контента. Обычно используются разметки структуры документа, когда отсутствует содержание глав. Такие главы отображаются как неактивные ссылки в оглавлении. Главы-черновики пишутся как обычные главы, но без записи пути к файлу

2.1.1.5 Разделитель Разделитель добавляет полосу, отделяющую одну часть оглавления от другой Разделитель - это строка, содержащая три и более тире: ---

2.2 Файловая структура при документировании Для удобства разработки документации, формирования понятной файловой структуры и корректного отображения содержимого генерируемой веб-страницы необходимо следовать следующим правилам:

Файлы, описывающие каждый раздел необходимо располагать согласно структуре оглавления Для каждого раздела создаётся директория; для корневых разделов директории с описанием находятся в корне проекта src Если раздел содержит подразделы, создаются поддиректории внутри раздела В директории каждого раздела находятся файл с расширением .md, с документацией соответствующей главы Названия всех папок и файлов должны быть без пробелов Если раздел или подраздел содержит изображения, в соответствующей директории создаётся папка assets, в которой размещаются файлы изображений Изображения именуются как asset_1, asset_2, ... и т.д. в том порядке, в котором они расположены в разделе документации, к которому относятся Ниже приведён пример оглавления в SUMMARY.md и соответствующая ему файловая структура

Оглавление в SUMMARY.md:

[Общая информация]()

1. Глава 1

- [Назначение и общие сведения]()

   - [Общие приёмы работы]()
   - [Общий порядок работы]()

---

1. Глава 2

- [Описание работы и синтаксиса скриптов](Описание_работы_и_синтаксиса_скриптов/Описание_работы_и_синтаксиса_скриптов.md)

 - [Типы данных](Описание_работы_и_синтаксиса_скриптов/1.Типы_данных/1.Типы_данных.md)
 - [Операторы](Описание_работы_и_синтаксиса_скриптов/2.Операторы/2.Операторы.md)
 - [Переменные](Описание_работы_и_синтаксиса_скриптов/3.Переменные/3.Переменные.md)
 - [Функции и методы](Описание_работы_и_синтаксиса_скриптов/4.Функции_и_методы/4.Функции_и_методы.md)
 - [Синтаксические конструкции](Описание_работы_и_синтаксиса_скриптов/5.Синтаксические_конструкции/5.Синтаксические_конструкциию.md)
 - [Примеры и комментарии](Описание_работы_и_синтаксиса_скриптов/6.Примеры/6.Примеры.md)

[Инструкция по документированию](readme.md) Файловая структура:

19

2.3 Работа с markdown файлами При написании документации в markdown редактировать содержимое можно либо вручную, либо через графический интерфейс VSCode

Для "ручного" редактирования - инструкция по использованию markdown: https://gist.github.com/Jekins/2bf2d0638163f1294637

Для редактирования через интерфейс VSCode можно использовать как стандартный функционал, так и расширения

Использование стандартного функционала:

Выделить текст и нажать по нему ПКМ Нажать "Рефакторинг" Выбрать необходимую функцию из появившегося списка или "Дополнительно" Через расширение EasyMarkdown:

установить расширение выделить редактируемый текст нажать на одну из кнопок редактирования текста в правом верхнем углу окна просмотра документа

Фиксация изменений и отправка в удаленный репозиторий GitLab

Для контроля вносимых в документацию изменений и их публикации на gitlab используется система контроля версий GIT

Перед началом работы с GIT необходимо его установить на компьютер и склонировать репозиторий (см. п. 1.2)

Алгоритм работы с GIT следующий:

Создаётся отдельная ветка, в которой будет работать только один разработчик документации Если работа производится в уже существующей ветке, то подгружается актуальная документация из удалённого репозитория в ветку main из которой добавляются изменения, внесённые другими пользователями, в текущую рабочую ветку Изменения в документации подготавливаются к фиксации - все, либо выборочно (добавляются в индекс) Изменения фиксируются (делается коммит) с кратким описанием Зафиксированные изменения публикуются на gitlab 3.1 Создание отдельной ветки В GIT новую ветку можно создать из любой другой, но в данной инструкции рассмотрен случай, когда все ветки создаются из одной главной - main.

В нижнем левом углу выберите ветку (по умолчанию это обычно main или master). Нажмите на название ветки и выберите Создать новую ветвь.

20

Введите название новой ветки и подтвердите создание, нажав Enter. После подтверждения создания ветки произойдёт автоматическое переключение на неё. В новой ветке будут все изменения (коммиты) ветки, из которой она создавалась

21

3.1.1 Работа с существующей веткой Если необходимо внести изменения в уже существующую ветку, созданную из главной - main, сначала подгружаются все актуальные изменения из main, текущая ветка сливается с main решаются конфликты (если возникают), и только после этого вносятся изменения в текущую рабочую ветвь. Такой алгоритм позволяет уменьшить количество конфликтов и работать с актуальной версией документации в своей ветке.

3.1.1.1 Подгрузка актуальных изменений Первым делом необходимо переключиться на ветку main (предварительно зафиксировав внесённые в свою ветку изменения - см п.3.2, 3.3): В левом нижнем углу экрана нажимаем на название текущей ветки Нажмите на название ветки и выберите main из списка вверху посередине экрана.

22

Затем нажимаем на Git Graph и Fetch From Remote как показано на рисунке ниже.

23

3.1.1.2 Слияние текущей рабочей ветки с main Переключитесь на рабочую ветку аналогично п.3.1.1.1. Затем в разделе Git Graph найдите последний коммит ветки main вверху появившегося списка коммитов и через контекстное меню, вызванное ПКМ произведите слияние с веткой main:

24 25

3.1.1.3 разрешение конфликтов при слиянии В процессе слияния рабочей ветки с main могут возникнуть конфликты, в случае если в двух разных ветвях (например main и readme-develop) были зафиксированы изменения в одном и том же файле.

При этом появится сообщение, в котором указаны файлы с конфликтующими изменениями:

26

Файлы, в которых возник конфликт подсвечиваются красным цветом в проводнике. Далее разрешаются конфликты для каждого файла после нажатия на кнопку Разрешить в редакторе слияния. GIT предложит принять изменения либо из рабочей ветки, либо из той, которая сливается с рабочей, либо принять изменения из обоих веток. 27

После разрешения всех конфликтов производится фиксация изменений (коммит), см. п.3.2, 3.3

3.2 Подготовка изменений к фиксации После внесения изменений в документы, откройте вкладку "Система управления версиями" (значок с тремя точками и линиями). Здесь располагается список изменённых файлов. Чтобы добавить изменения в индекс, нужно нажать знак «+» рядом с каждым файлом (или напротив "Изменения", чтобы добавить все файлы сразу).

28

3.3 Создание коммита После добавления изменений в индекс в поле ввода "Сообщение" вверху вкладки "Система управления версиями" пишется краткое описание изменений (например, "Добавлена глава..."). Нажмите на синюю кнопку "Фиксация" для фиксации изменений (коммит).

29

3.4 Публикация изменений на GitLab После создания коммита нажмите на кнопку "Опубликовать ветку" если рабочая ветка ранее не публиковалась на gitlab или "Синхронизировать изменения", чтобы загрузить изменения в существующую ветку Эта кнопка отправит изменения на удалённый репозиторий GitLab.

30

31

Проверка и утверждение изменений в Merge Request

Если внесённые изменения находятся в отдельной ветке GIT, они должны быть добавлены в одну единственную, главную ветку (обычно main), в которой находится вся остальная документация.

Для этого необходимо выполнить следующее:

Зайти на страницу с репозиторием, в данном случае https://gitlab.chemsoft.ru/chemic3-group/chemsoft-docs-content Создать запрос на слияние (merge request) одним из двух способов: через вкладку Merge requests в боковом меню слева с помощью кнопки, появляющейся в верхней части окна после внесения изменений на gitlab При первом способе после нажатия на вкладку Merge requests в разделе Code левого бокового меню происходит перенаправление на страницу, где нужно нажать на кнопку New merge request 32 33 После этого происходит перенаправление ещё на одну страницу, где необходимо указать ветку с изменениями (Source branch - слева) и ветку для слияния (Target branch - справа), и нажать на кнопку Compare branches and continue

34 На следующей странице необходимо настроить запрос на слияние, а именно:

Указать заголовок merge request Добавить описание merge request Назначить ответственного Назначить проверяющего Нажать кнопку Create merge request 36 При втором способе после нажатия кнопки Create Merge Request проделываются шаги 1-5, описанные выше. 37

На странице запроса на слияния происходит подтверждение слияния с веткой проверяющим нажатием на кнопку Merge При этом есть возможность для просмотреть изменения, и оставить комментарий (замечания) к запросу.

Сообщение Ready to merge! означает что конфликты между ветками отсутствуют и они готовы к слиянию. Если возникают конфликты, вместо этого сообщения будет соответствующее предупреждающее сообщение. В этом случае необходимо разрешить конфликты следуя пунктам 3.1.1.1, 3.1.1.2, 3.1.1.3 и опубликовать рабочую ветвь без конфликтов (п.3.3, 3.4), после чего вернуться к запросу на слияние на gitlab и убедиться в готовности к слиянию.

Так же при слиянии существуют дополнительные действия:

Delete source branch - удаление рабочей ветки Squash commits - Объединение коммитов в один Edit commit message - Редактирование сообщения к коммиту 38

Автоматическая генерация HTML-страниц и обновление сайта

После подтверждения merge request автоматически генерируется пакет с WEB страницами, включающие все последние изменения репозитория и публикует по адресам:

https://astra.chemsoft.ru/doc https://triteia.chemsoft.ru/doc

Пример сформированного документа:

1

Справочник состоит из оглавления в левой части интерфейса, и контента справа, отображающего содержимое выбранной главы.

Для удобства работы пользователя доступны функции навигации, поиска и смены цветовой темы.