Дополнение # Dutch Biblical Studie для NVDA

Этот пакет содержит базовую структуру шаблонов для разработки, сборки, распространения и локализации дополнений для NVDA.
Для получения подробной информации о разработке дополнений для NVDA, пожалуйста, обратитесь к Руководству по разработке дополнений для NVDA.
Список разработки/обсуждения дополнений NVDA находится здесь.
Информация о магазине дополнений NV Access находится здесь.

Copyright (C) 2012-2024 Соавторы команды NVDA Add-on.

Этот пакет распространяется на условиях Стандартной общественной лицензии GNU, версия 2 или более поздняя. Более подробная информация приведена в файле COPYING.txt.

alekssamos добавлен автоматический пакет дополнений через Github Actions.

Подробнее о Github Actions смотрите в статье Синтаксис рабочего процесса для GitHub Actions.

Copyright (C) 2022 alekssamos

Особенности

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

• Автоматическое создание пакета дополнения, с именованием и версией, загружаемой из централизованного файла переменных сборки (buildVars.py) или интерфейса командной строки.
  • Подробнее об использовании переключателей командной строки при упаковке дополнений с пользовательской информацией о версии смотрите в разделе «Упаковка».
  • Этот процесс будет происходить автоматически при получении pull request, также есть возможность ручного запуска.
  • Чтобы рабочий процесс запускался автоматически при проталкивании в главную или master (development) ветку, удалите комментарий к строке branches в GitHub Actions (.github/workflows/build_addon.yml).
  • Если вы создали тег (например: git tag v1.0 && git push --tag), то автоматически будет создан релиз и файл дополнения будет загружен как актив.
  • В противном случае, при обычных коммитах или при ручном запуске, вы можете загрузить артефакты со страницы Actions вашего репозитория.
• Создание файла манифеста с помощью шаблона (manifest.ini.tpl). Переменные сборки заменяются на этот шаблон. Спецификацию манифеста дополнений смотрите ниже.
• Компиляция gettext mo файлов перед распространением, когда это необходимо.
  • Чтобы сгенерировать gettext pot-файл, выполните команду scons pot. Будет создан файл addon-name.pot со всеми gettext-сообщениями для вашего дополнения. Вам необходимо проверить переменную buildVars.i18nSources на соответствие вашим требованиям.
• Автоматическая генерация файлов локализации манифеста непосредственно из gettext po файлов. Убедитесь, что buildVars.py включен в i18nFiles.
• Автоматическая генерация HTML-документов из файлов markdown (.md) для управления документацией на разных языках.

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

• Ruff (секции pyproject.toml/tool.ruff): Python-линтер, написанный на Rust. Разделы, начинающиеся с tool.ruff, содержат параметры конфигурации для Ruff.
• Конфигурация для VS Code. Она требует наличия репозитория NVDA на том же уровне, что и папка дополнения, содержащая ваши фактические исходные файлы, с подготовленным исходным кодом (scons source). Подготовка исходного кода - это шаг в инструкции по сборке самой NVDA, подробности см. в The NVDA Repository.
  * Поместите .vscode из этого репозитория в папку addon, где будут находиться исходные файлы вашего дополнения. Файл настроек в этой папке предполагает, что репозиторий NVDA находится в родительской папке этой папки. Если папка с аддоном находится в папке addonTemplate, то папка с хранилищем NVDA также должна находиться в папке addonTemplate, иначе источник не будет найден.
  * Откройте папку аддона в VS Code. Это должно инициализировать VS Code с правильными настройками и предоставить вам возможность завершения кода и другие возможности VS Code.
  • Нажмите control+shift+m после сохранения файла для поиска проблем.
  • Используйте клавиши со стрелками и табуляцией для автозавершения.
  • Нажмите control+shift+p, чтобы открыть палитру команд и найти рекомендуемые для установки расширения или проверить, установлены ли они.

Требования

Чтобы использовать этот код для разработки и упаковки дополнений NVDA, вам потребуется следующее программное обеспечение:

• дистрибутив Python (рекомендуется 3.11 или более поздняя версия). Установщики для Windows можно найти на Python Website. Обратите внимание, что в настоящее время для подготовки исходного кода NVDA требуется 32-битная версия Python 3.11.
• Scons - Сайт - версия 4.5.2 или более поздняя. Вы можете установить его через PIP.
• GNU Gettext tools, если вы хотите иметь поддержку локализации для вашего дополнения - Рекомендуется. Они установлены в любом дистрибутиве Linux или cygwin. Сборки для windows можно найти здесь.
• Markdown 3.3.0 или более поздней версии, если вы хотите конвертировать файлы документации в HTML-документы. Вы можете установить его через PIP.

Обратите внимание, что эти инструменты могут не понадобиться вам в локальной среде сборки, если вы используете Appveyor или GitHub Actions для сборки и упаковки ваших дополнений.

Использование

Чтобы создать новое дополнение NVDA с помощью этого шаблона, выполните следующие действия:

1. Создайте пустую папку, в которой будут храниться файлы вашего дополнения.
2. Скопируйте папку:

site_scons

и следующие файлы в новую пустую папку:

buildVars.py
manifest.ini.tpl
manifest-translated.ini.tpl
sconstruct
.gitignore
.gitattributes

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

.github

и файл:

.pre-commit-config.yaml

4. Создайте папку addon внутри вашей новой папки. Вы поместите свой код в обычные папки для расширений NVDA, в папку addon. Например: globalPlugins, synthDrivers и т.д.
5. В файле buildVars.py измените переменную addon_info на информацию о вашем дополнении (название, резюме, описание, версия, автор, url, url источника, лицензия и URL лицензии). Также не забудьте тщательно задать пути, содержащиеся в других переменных этого файла. Если вам необходимо использовать пользовательские расширения Markdown, исходный язык интерфейса дополнения не английский или включать пользовательские таблицы перевода Брайля, не забудьте отфильтровать список markdown, переменную базового языка и диктовку таблиц Брайля соответственно.
6. Переводы Gettext должны быть помещены в файл addon\locale\<lang>/LC_MESSAGES\nvda.po.

Спецификация манифеста дополнения

Манифест дополнения, созданный вручную или с помощью buildVars.py, должен содержать следующую информацию:

• Имя (строка): уникальный идентификатор дополнения. В нем должен использоваться верблюжий регистр (например, someModule). Это имя также используется в хранилище дополнений для уникальной идентификации дополнения.
• Summary (строка): название, отображаемое в магазине дополнений NVDA.
• Описание (строка): краткое подробное описание дополнения.
• Версия (строка), в идеале номер.номер с необязательным третьим номером, обозначающим major.minor.patch.
• Автор (строка и адрес электронной почты): одна или несколько контактных данных автора дополнения в форме «имя ».
• URL (строка): веб-адрес, по которому можно найти информацию о дополнении, например, репозиторий дополнений.
• docFileName (строка): имя файла документации.
• minimumNVDAVersion (year.major или year.major.minor): самая ранняя версия NVDA, с которой совместимо дополнение (например, 2019.3). Ожидается, что дополнения будут использовать функции, представленные в этой версии NVDA, или заявят о совместимости с ней.
• lastTestedNVDAVersion (year.major или year.major.minor): последняя или последняя протестированная версия NVDA, с которой, как утверждается, совместимо дополнение (например, 2020.3). Ожидается, что авторы дополнений объявят это значение после тестирования дополнений с указанной версией NVDA.
• addon_updateChannel (string или None): канал обновления для релиза дополнения.

Кроме того, в buildVars должна быть заполнена следующая информация (не используемая в манифесте, но используемая в других местах, например, в магазине дополнений):

• sourceURL (строка): URL-адрес репозитория для исходного кода дополнения.
• license (string): лицензия дополнения и его исходного кода.
• licenseURL: URL-адрес файла лицензии.

Пользовательская дополнительная информация

В дополнение к основным данным манифеста можно указать пользовательскую дополнительную информацию. Начиная с 2024 года, шаблон поддерживает генерацию пользовательских таблиц перевода Брайля. Информация о пользовательских таблицах Брайля должна быть указана в buildVars в словаре braileTables следующим образом:

• Имя таблицы (строковый ключ для вложенного словаря): каждая запись brailleTables - это имя файла для включенной пользовательской таблицы Брайля, помещенной в папку brailleTables внутри папки addon. В этом вложенном словаре должны быть указаны:
  • displayName (строка): название таблицы, отображаемое пользователям и поддающееся переводу.
  • contracted (True/False): является ли эта таблица сокращенным шрифтом Брайля (True) или не сокращенным (False).
  • вывод (True/False): таблица может быть выведена в список выводимых таблиц в настройках Брайля NVDA.
  • ввод (True/False): шрифт Брайля может быть введен с помощью этой таблицы и указан в списке таблиц ввода в настройках Брайля NVDA.

Примечание: вы должны заполнить этот словарь, если хотя бы одна пользовательская таблица Брайля включена в дополнение. Если нет, оставьте словарь пустым.

Чтобы управлять файлами документации для вашего аддона:

1. Скопируйте файл readme.md для вашего дополнения в первую созданную папку, куда вы скопировали buildVars.py. Вы также можете скопировать style.css для улучшения представления HTML-документов.
2. Файлы документации (с именем readme.md) должны быть помещены в папку addon\doc\<lang>/.

Чтобы упаковать дополнение для распространения:

1. Откройте командную строку, перейдите в папку с файлом sconstruct (обычно это корень папки разработки дополнения) и выполните командуscons`. Созданное дополнение, если не было ошибок, будет помещено в текущую директорию.
2. Вы можете дополнительно настроить переменные в файле buildVars.py.
3. Вы также можете настроить информацию о версии и канале обновления из командной строки, передав следующие ключи при запуске scons:
   • version: строка версии дополнения.
   • versionNumber: номер версии дополнения в виде major.minor.patch (все целые числа)
   • channel: канал обновления (не используйте этот ключ, если не знаете, что делаете).
   • dev: подходит для сборок разработки, называет дополнение в соответствии с текущей датой (yyyymmdd) и устанавливает канал обновления на «dev».

Дополнительные инструменты

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

• Ruff (pyproject.toml): линтер для Python, написанный на Rust (0.4.10 или более поздняя версия, может быть установлен с помощью PIP).

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

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

Если у вас возникнут какие-либо проблемы, воспользуйтесь списком аддонов NVDA, упомянутым выше.