Настройка и инструменты#

Документация создается с помощью инструмента генерации статических файлов Sphinx из исходных файлов, описанный в формате Rst (ReStructuredText). В результате обработки исходных текстов создается набор файлов документации в формате html, который может быть использован для публикации на сайте.

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

Свободно распространяемый редактор VisualStudio Code.
Интерпретатор языка Python.

Все ПО для создания документации полностью настроено с помощью файлов конфигураций для соответствующих программ.

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

Редактор VSCode позволяет:

Редактировать файлы документации с использованием подсветки синтаксиса и структуры документа.
Переходить по ссылкам между элементами документации.
Отображать редактируемый файл в окне предварительного просмотра в реальном времени.
Автоматически генерировать выходные файлы для измененных файлов документации.

Исходный текст документации и все файлы необходимые для ее редактирования и создания конечного продукта расположены в репозитории IngortechSCADA.

Для редактирования документации необходимо:

Получить доступ к репозиторию IngortechSCADA.
Установить и настроить инструменты для контроля версий Git.
Создать локальную копию репозитория на своем компьютере и связать ее с репозиторием IngortechSCADA.
Установить и настроить редактор VSCode.
Установить интерпретатор языка Python и модули, необходимые для создания сайта документации.

Установка VSCode#

Установить VSCode можно скачав дистрибутив по ссылке:

https://code.visualstudio.com/download

При этом необходимо выбрать установочный пакет, соответствующий способу использования из набора «User Installer» и «System Installer».

Рекомендуется использовать «System Installer».

Устанавливать можно в любой каталог, однако в документации подразумевается, что VSCode был установлен в каталог:

C:\VSCode

Предупреждение

После установки не нужно сразу же запускать VSCode. Для работы необходимо подключить репозитории и произвести его настройку из файлов репозитория.

Настройка репозитория#

Скачать утилиту для контроля версий по ссылке:
```
https://gitforwindows.org
```

Получить доступ к репозиторию IngortechSCADA
Инициализировать локальный репозиторий с помощью команд:
```
// Инициализация
git init
```
В локальном каталоге репозитория, в файле:
```
.git\config
```
Установить параметры доступа в формате:
```
[user]
 email = <USER>@git.ingortech.ru
 user = <USER>
 name = <USER>
[credential]
 helper = store
```
Где указать свои идентификационные данные.
В локальном каталоге репозитория создать файл «.commitmsg» для автоматической идентификации отправляемых данных. В котором указать свое имя в произвольном формате.
```
Иванов Петр
```
Этот файл будет использоваться для идентификации автора вносимых изменений при отправке данных на сервер.

Настроить доступ к репозиторию.

// Настройка сообщения отправки по умолчанию
git config --local commit.template .commitmsg

// Связь с репозиторием IngortechSCADA
git remote add origin https://git.ingortech.ru/git/<USER>/<REPO>.git

// Скачать основную ветку
git pull https://git.ingortech.ru/git/<USER>/<REPO>.git master

// Установить связь для скачивания и отправки
git pull --set-upstream origin master
git push --set-upstream origin master

В командах заменить соответствующие поля своими данными и названием репозитория IngortechSCADA.

В дальнейшем, для отправки и получения данных из репозитория, использовать команды Git вручную или использовать соответствующие инструменты VSCode.

Установка и настройка Python#

Установить интерпретатор языка Python, скачав дистрибутив по ссылке:
```
https://www.python.org/downloads
```
Установить необходимый набор расширений языка запустив файл install.bat из каталога репозитория.

Настройка VSCode#

Для работы с документацией необходимо установить несколько общедоступных расширений, а так же применить собственные настройки и расширения для работы с документацией.

Собственные настройки

Применить настройки для редактора выполнив файл vscode_RestoreSettings.bat из каталога репозитория.
Установить расширение редактора выполнив файл copy-to-exts.bat из каталога репозитория.

Общедоступные расширения

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

reStructuredText.
Extension Pack for reStructuredText.
reStructuredText Syntax highlighting.

А так же все расширения, которые будут предложены в процессе установки.

В результате настройки и установки, в редакторе должен отображаться следующий набор расширений:

../_images/addons.png — Набор расширений VSCode#

Просмотр сайта в браузере#

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

После его выполнения на экране откроется окно консоли, в котором будет выполняться программа сервер sphinx-autobuild.

../_images/sphinx-autobuild.png — Работа утилиты автоматического обновления документации#

После запуска утилиты и завершения первоначальной генерации документации в консоли будет выведен адрес, к которому необходимо подключить локальный броузер для просмотра документации (в примере выше это http://127.0.0.1:8000).