Тестирование MyST Substitutions

Эта страница демонстрирует все возможности глобальных замен (substitutions) в документации ЭКНИС.

🎯 Основные тесты

Простые замены

• Текстовая замена: SUB_OK

• Иконка меню:

• Иконка выключения:

Ожидаемый результат:

• SUB_OK должно стать “SUB_OK”

• должно стать HTML-тегом с иконкой меню

• должно стать HTML-тегом с иконкой выключения

📋 Доступные иконки

Основные действия

• - Меню системы

• - Выключение системы

• - Настройки системы

• - Восстановление резервной копии

🔧 Примеры использования в тексте

Процедура выключения

1. Сохраните все изменения

2. Нажмите для выключения системы

3. Подтвердите действие в диалоге

Навигация по системе

1. Откройте главное меню

2. Выберите нужный раздел

3. Выполните необходимые действия

Процедура завершения работы

• Нажмите для доступа к функциям

• Выберите для выключения

• Подтвердите завершение работы

🧪 Тестирование разных синтаксисов

Синтаксис 1: (правильный)

SUB_OK

Синтаксис 2: {name} (неправильный)

{_test_sub} {menu} {turn_off}

Синтаксис 3: |name| (неправильный)

|_test_sub| |menu| |turn_off|

📖 Примеры в контексте

В процедурах

1. Откройте {{ menu }} главное меню
2. Выберите {{ turn_off }} Выключение
3. Подтвердите действие

В списках

- {{ menu }} Главное меню
- {{ turn_off }} Выключение системы

В предупреждениях

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

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

🔧 Техническая информация

Пути к файлам

• Global: /static/icons/global/menu.png

• Global: /static/icons/global/turn_off.png

CSS классы

• ui-icon - стандартный размер (16x16px)

• ui-icon-large - увеличенный размер (24x24px)

Формат иконок

• PNG для совместимости

• Оптимизированные размеры

• Прозрачный фон

Конфигурация

# В source/conf.py
myst_substitutions = {
    "_test_sub": "SUB_OK",
    "menu": '<img src="/_static/icons/global/menu.png" alt="Меню" class="ui-icon">',
    "turn_off": '<img src="/_static/icons/global/turn_off.png" alt="Выключить" class="ui-icon">',
}

🎨 Принципы использования

Иконки в тексте

• Использовать для UI элементов

• Консистентность - одинаковые иконки для одинаковых действий

• Читаемость - иконки должны быть понятны без дополнительного объяснения

Текстовые замены

• Использовать для часто повторяющихся фраз

• Краткие и понятные ключи

• Избегать конфликтов с обычным текстом

🚀 Добавление новых замен

1. Размещение файла иконки

# Скопировать PNG файл в папку global
cp new-icon.png source/_static/icons/global/

2. Обновление conf.py

myst_substitutions = {
    # ... существующие замены ...
    "new_icon": '<img src="/_static/icons/global/new-icon.png" alt="Описание" class="ui-icon">',
}

3. Использование в документации

Нажмите {{ new_icon }} для выполнения действия.

🧪 Проверка работы

Автоматическая проверка

# Сборка документации
sphinx-build -b html -a -E -c ./source ./source ./_build/html

# Открыть тестовую страницу
open _build/html/test-substitutions.html

Ручная проверка

1. Убедиться, что иконки отображаются

2. Проверить, что текстовые замены работают

3. Убедиться, что CSS классы применяются

4. Проверить пути к файлам

📚 Дополнительная документация

• STYLE_GUIDE.md - руководство по стилю

• Конфигурация - настройки Sphinx и иконки (myst_substitutions)