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

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

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

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

  • Интерпретатор языка Python.

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

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

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

  1. Редактировать файлы документации с использованием подсветки синтаксиса и структуры документа.

  2. Переходить по ссылкам между элементами документации.

  3. Отображать редактируемый файл в окне предварительного просмотра в реальном времени.

  4. Автоматически генерировать выходные файлы для измененных файлов документации.

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

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

  1. Получить доступ к репозиторию IngortechSCADA.

  2. Установить и настроить инструменты для контроля версий Git.

  3. Создать локальную копию репозитория на своем компьютере и связать ее с репозиторием IngortechSCADA.

  4. Установить и настроить редактор VSCode.

  5. Установить интерпретатор языка Python и модули, необходимые для создания сайта документации.

Установка VSCode#

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

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

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

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

C:\VSCode

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

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

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

  1. Скачать утилиту для контроля версий по ссылке:

    https://gitforwindows.org

  1. Получить доступ к репозиторию IngortechSCADA

  2. Инициализировать локальный репозиторий с помощью команд:

    // Инициализация
git init

  3. В локальном каталоге репозитория, в файле:

    .git\config

    Установить параметры доступа в формате:

    [user]
 email = <USER>@git.ingortech.ru
 user = <USER>
 name = <USER>
[credential]
 helper = store

    Где указать свои идентификационные данные.

  4. В локальном каталоге репозитория создать файл «.commitmsg» для автоматической идентификации отправляемых данных. В котором указать свое имя в произвольном формате.

    Иванов Петр

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

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

    // Настройка сообщения отправки по умолчанию
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 из каталога репозитория.

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

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

Название

Версия

esbonio

0.15.0

sphinx

5.3.0

Настройка VSCode#

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

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

  • Применить настройки для редактора выполнив файл vscode_RestoreSettings.bat из каталога репозитория.

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

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

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

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

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

Для смены версии расширения, на странице информации о расширении, в верхней части, необходимо вызвать выпадающий список версий у кнопки «Удалить» и выбрать пункт «Установить определенную версию».

../_images/version.png

При этом обязательно необходимо отключить автоматическое обновление расширений.

Для работы необходимо установить следующие расширения:

Название

Версия

reStructuredText

189.3.0

Extension Pack for reStructuredText

1.0.3

Pylance

2024.2.4

Python

2023.14.0

Code Spell Checker

4.4.0

Russian - Code Spell Checker

2.2.4

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

../_images/addons.png

Набор расширений VSCode#

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

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

../_images/running.png

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

Вызвать окно предварительного просмотра можно нажав соответствующую кнопку в заголовке редактора для любого файла с расширением «RST» или нажать сочетание клавиш Ctrl+Shift+R. Окно предварительного просмотра можно разместить в любом удобном месте.

В дальнейшем, при редактировании текста документации в файлах с расширением «RST» в окне просмотра будет отображаться результат редактирования.

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

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

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

../_images/sphinx-autobuild.png

Работа утилиты автоматического обновления документации#

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