|
|
| (не показаны 33 промежуточные версии 1 участника) |
| Строка 1: |
Строка 1: |
| '''Справочная документация''' - для Веб-ЛИМС "Тритея" представляет собой связанный набор HTML-страниц, размещенных по ссылкам: | | '''Справочная документация''' - для <code>Веб-ЛИМС "Тритея"</code> представляет собой связанный набор HTML-страниц, размещенных на демо-стендах по ссылкам: |
| *https://triteia.chemsoft.ru/doc | | *https://triteia.chemsoft.ru/doc |
| *https://astra.chemsoft.ru/doc | | *https://astra.chemsoft.ru/doc |
|
| |
|
| '''Этапы документирования Веб-ЛИМС'''
| | Так же данная документация упаковывается в docker-контейнер (дистрибутив) для дальнейшей передачи наработок Пользователям. |
|
| |
|
| #[[Работа со справочной документацией#Настройка локального рабочего окружения|Настройка локального рабочего окружения]]
| | ==Этапы документирования Веб-ЛИМС== |
| #[[Работа со справочной документацией#Формирование и актуализация Markdown-исходников документации|Формирование и актуализация Markdown-исходников документации]]
| |
| #[[Работа со справочной документацией#Фиксация изменений и отправка в удаленный репозиторий GitLab|Фиксация изменений и отправка в удаленный репозиторий GitLab]]
| |
| #[[Работа со справочной документацией#Проверка и утверждение изменений в Merge Request|Проверка и утверждение изменений в Merge Request]]
| |
| #[[Работа со справочной документацией#Автоматическая генерация HTML-страниц и обновление сайта|Автоматическая генерация HTML-страниц и обновление сайта]]
| |
|
| |
|
| ==Настройка локального рабочего окружения== | | ===[[Настройка локального рабочего окружения|1. Настройка локального рабочего окружения]]=== |
| Для создания, редактирования и публикации документов вам потребуется любой текстовый редактор или среда разработки (<code>IDE</code>) с поддержкой формата <code>Markdown</code> и встроенной системой контроля версий <code>Git</code>.
| |
|
| |
|
| Вы можете использовать привычный для себя инструмент (например, <code>WebStorm</code>, <code>Obsidian</code>, <code>Sublime Text</code>).
| | ===[[Формирование и актуализация Markdown-исходников документации|2. Формирование и актуализация Markdown-исходников документации]]=== |
|
| |
|
| Если у вас нет предпочтений, рекомендуется использовать <code>Visual Studio Code</code> — бесплатный кроссплатформенный редактор, в котором по умолчанию есть все необходимые инструменты для работы.
| | ===[[Фиксация изменений и отправка в удаленный репозиторий GitLab|3. Фиксация изменений и отправка в удаленный репозиторий GitLab]]=== |
|
| |
|
| Скачать дистрибутив: https://code.visualstudio.com/
| | ===[[Проверка и утверждение изменений в Merge Request|4. Проверка и утверждение изменений в Merge Request]]=== |
|
| |
|
| ===Visual Studio Code=== | | ===[[Автоматическая генерация HTML-страниц и обновление сайта|5. Автоматическая генерация HTML-страниц и обновление стендов]]=== |
| 1.1.1 Начало работы и общие сведения
| |
| Слева в верхней части интерфейса находятся вкладки, необходимые для работы.
| |
| Для документирования понадобятся:
| |
| | |
| Проводник
| |
| Система управления версиями
| |
| Расширения
| |
| 2
| |
| | |
| Для начала работы открыть директорию с проектом выполнив действия:
| |
| | |
| Выбрать файл в верхнем левом углу
| |
| В появившемся меню нажать Открыть папку...
| |
| Найти и выбрать папку с документацией, предварительно скачанной из gitlab
| |
| 3
| |
| 4
| |
| | |
| Во вкладке Проводник сверху появится строка с названием папки.
| |
| Чтобы работать с её содержимым, развернуть, нажав на её название
| |
| 5
| |
| | |
| Развёрнутая папка проекта:
| |
| | |
| 6
| |
| | |
| Чтобы создать файл или папку необходимо выделить директорию и нажать на кнопку Создать файл... или Создать папку:
| |
| | |
| 7
| |
| | |
| Содержимое открытых файлов отображается в правой части интерфейса VSCode.
| |
| Для файлов расширения markdown (.md) по умолчанию предусмотрен предпросмотр (кнопка Открыть область предварительного просмотра справа в верхнем правом углу):
| |
| | |
| 8
| |
| 9
| |
| | |
| Выбрать действие над файлом или папкой можно вызвав контекстное меню, нажатием ПКМ:
| |
| 10
| |
| | |
| 1.1.2 установка русского языка для интерфейса VSCode
| |
| ввести команду: Ctrl + Shift + P, в верху экрана посередине появится поле ввода команд
| |
| 11
| |
| | |
| ввести команду Configure Display Language и нажимаем Enter
| |
| | |
| ввести русский и нажать Enter
| |
| | |
| 12
| |
| | |
| Нажимаем restart, тем самым перезапуская Visual Studio Code и применяя русский интерфейс к программе:
| |
| 13
| |
| 1.1.3 Расширения:
| |
| 1.1.3.1 Russian - Code Spell Checker
| |
| Автоматически проверяет орфографию
| |
| | |
| Установка расширения:
| |
| | |
| перейти во вкладку "Расширения"
| |
| ввести в поиск Russian - Code Spell Checker
| |
| нажать синюю кнопку install
| |
| 14
| |
| | |
| После установки нажать F1 (появится поле ввода вверху экрана) и ввести в поле:
| |
| | |
| Enable Russian Spell Checker Dictionary, нажать Enter
| |
| | |
| Disable Russian Spell Checker Dictionary in Workspace, нажать Enter
| |
| | |
| 15
| |
| | |
| Настройка завершена !
| |
| | |
| 1.1.3.2 EasyMarkdown
| |
| Добавляет некоторые функции в интерфейс VSCode для быстрого редактирования markdown:
| |
| | |
| 16
| |
| | |
| Добавленные функции:
| |
| | |
| 17
| |
| | |
| ===Система контроля версий GIT===
| |
| Для установки модулей и настройки авторизации в gitlab необходимо воспользоваться помощью программиста.
| |
| | |
| ==Формирование и актуализация Markdown-исходников документации==
| |
| | |
| Формирование структуры и содержимого документации, путём создания (редактирования) файлов расширения markdown, являющегося отдельным документом с соответствующего определённой главе или подразделу, распределение .md файлов в файловой структуре согласно иерархии
| |
| | |
| 2.1 Создание оглавления
| |
| Файл SUMMARY.md необходим для формирования заголовков документации, их последовательности и иерархии.
| |
| Файл является неотъемлемой частью документации и должен находиться только в корне проекта.
| |
| | |
| Форматирование файла-оглавления должно осуществляться согласно правилам, описанным ниже. Любое отклонение от правил форматирования приведёт к игнорированию внесённых изменений или может вызвать ошибку при создании структуры документа.
| |
| | |
| Оглавление, описанное в SUMMARY.md состоит из элементов, каждый из которых определяет то, какой будет структура оглавления и каким будет контент каждой главы в итоговом документе
| |
| | |
| 2.1.1 Элементы оглавления в SUMMARY.md
| |
| Пример оглавления в SUMMARY.md может выглядеть следующим образом:
| |
| | |
| [Общая информация]() | |
| | |
| # Глава 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
| |
| - [Назначение и общие сведения]()
| |
| - [Общие приёмы работы]()
| |
| - [Общий порядок работы]()
| |
| | |
| ---
| |
| | |
| # Глава 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
| |
| | |
| Справочник состоит из оглавления в левой части интерфейса, и контента справа, отображающего содержимое выбранной главы.
| |
| | |
| Для удобства работы пользователя доступны функции навигации, поиска и смены цветовой темы.
| |
