nvdaaddons/addontemplate

Template and metadata used by NVDA community add-ons

NVDA Add-on Scons Template

This package contains a basic template structure for NVDA add-on development, building, distribution and localization. For details about NVDA add-on development, please see the NVDA Add-on Development Guide. The NVDA add-on development/discussion list is here Information specific to NV Access add-on store can be found here.

Copyright (C) 2012-2024 NVDA Add-on team contributors.

This package is distributed under the terms of the GNU General Public License, version 2 or later. Please see the file COPYING.txt for further details.

alekssamos added automatic package of add-ons through Github Actions.

For details about Github Actions please see the Workflow syntax for GitHub Actions.

Copyright (C) 2022 alekssamos

Features

This template provides the following features you can use during NVDA add-on development and packaging:

• Automatic add-on package creation, with naming and version loaded from a centralized build variables file (buildVars.py) or command-line interface.
  • See packaging section for details on using command-line switches when packaging add-ons with custom version information.
  • This process will happen automatically when receiving a pull request, and there is also the possibility of manual launch.
  • To let the workflow run automatically when pushing to main or master (development) branch, remove the comment for branches line in GitHub Actions (.github/workflows/build_addon.yml).
  • If you have created a tag (E.G.: git tag v1.0 && git push --tag), then a release will be automatically created and the add-on file will be uploaded as an asset.
  • Otherwise, with normal commits or with manual startup, you can download the artifacts from the Actions page of your repository.
• Manifest file creation using a template (manifest.ini.tpl). Build variables are replaced on this template. See below for add-on manifest specification.
• Compilation of gettext mo files before distribution, when needed.
  • To generate a gettext pot file, please run scons pot. An addon-name.pot file will be created with all gettext messages for your add-on. You need to check the buildVars.i18nSources variable to comply with your requirements.
• Automatic generation of manifest localization files directly from gettext po files. Please make sure buildVars.py is included in i18nFiles.
• Automatic generation of HTML documents from markdown (.md) files, to manage documentation in different languages.

In addition, this template includes configuration files for the following tools for use in add-on development and testing (see "additional tools" section for details):

• Flake8 (flake8.ini): a base configuration file for Flake8 linting tool based on NVDA's own Flake8 configuration file.
• Configuration for VS Code. It requires NVDA's repo at the same level as the add-on folder containing your actual source files, with prepared source code (scons source). preparing the source code is a step in the instructions for building NVDA itself, see The NVDA Repository for details. * Place the .vscode in this repo within the addon folder, where your add-on source files (will) reside. The settings file within this folder assumes the NVDA repository is within the parent folder of this folder. If your addon folder is within the addonTemplate folder, then your NVDA repository folder needs to also be within the addonTemplate folder, or the source will not be found. * Open the addon folder in VS Code. This should initialize VS Code with the correct settings and provide you with code completion and other VS Code features.
  • Press control+shift+m after saving a file to search for problems.
  • Use arrow and tab keys for the autocompletion feature.
  • Press control+shift+p to open the commands palette and search for recommended extensions to install or check if they are installed.

Requirements

You need the following software to use this code for your NVDA add-on development and packaging:

• a Python distribution (3.11 or later is recommended). Check the Python Website for Windows Installers. Please note that at present, preparing the NVDA source code requires the 32-bit version of Python 3.11.
• Scons - Website - version 4.5.2 or later. You can install it via PIP.
• GNU Gettext tools, if you want to have localization support for your add-on - Recommended. Any Linux distro or cygwin have those installed. You can find windows builds here.
• Markdown 3.3.0 or later, if you want to convert documentation files to HTML documents. You can install it via PIP.

Note, that you may not need these tools in a local build environment, if you are using Appveyor or GitHub Actions, to build and package your add-ons.

Usage

To create a new NVDA add-on using this template:

1. Create an empty folder to hold the files for your add-on.
2. Copy the folder:

site_scons

and the following files, into your new empty folder:

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

3. If you intend to use the provided GitHub workflow, also copy the folder:

.github

and file:

.pre-commit-config.yaml

4. Create an addon folder inside your new folder. You will put your code in the usual folders for NVDA extensions, under the addon folder. For instance: globalPlugins, synthDrivers, etc.
5. In the buildVars.py file, change variable addon_info with your add-on's information (name, summary, description, version, author, url, source url, license, and license URL). Also, be sure to carefully set the paths contained in the other variables in that file. If you need to use custom Markdown extensions, original add-on interface language is not English, or include custom braille translations tables, be sure to fil out markdown list, base language variable, and braille tables dictioanry, respectively.
6. Gettext translations must be placed into addon\locale\<lang>/LC_MESSAGES\nvda.po.

Add-on manifest specification

An add-on manifest generated manually or via buildVars.py must include the following information:

• Name (string): a unique identifier for the add-on. It must use camel case (e.g. someModule). This is also used as part of add-on store to identify the add-on uniquely.
• Summary (string): name as shown on NVDA's Add-on store.
• Description (string): a short detailed description about the add-on.
• Version (string), ideally number.number with an optional third number, denoting major.minor.patch.
• Author (string and an email address): one or more add-on author contact information in the form "name email@address".
• URL (string): a web address where the add-on information can be found such as add-on repository.
• docFileName (string): name of the documentation file.
• minimumNVDAVersion (year.major or year.major.minor): the earliest version of NVDA the add-on is compatible with (e.g. 2019.3). Add-ons are expected to use features introduced in this version of NVDA or declare compatibility with it.
• lastTestedNVDAVersion (year.major or year.major.minor): the latest or last tested version of NVDA the add-on is said to be compatible with (e.g. 2020.3). Add-on authors are expected to declare this value after testing add-ons with the version of NVDA specified.
• addon_updateChannel (string or None): the update channel for the add-on release.

In addition, the following information must be filled out (not used in the manifest but used elsewhere such as add-on store) in buildVars:

• sourceURL (string): repository URL for the add-on source code.
• license (string): the license of the add-on and its source code.
• licenseURL: the URL for the license file.

Custom add-on information

In addition to the core manifest data, custom add-on information can be specified. As of 2024, the template supports generation of custom braille translation tables. Information on custom braille tables must be specified in buildVars under braileTables dictionary as follows:

• Table name (string key for a nested dictionary): each brailleTables entry is a filename for the included custom braille table placed in brailleTables folder inside addon folder. This nested dictionary should specify:
  • displayName (string): the name of the table shown to users and is translatable.
  • contracted (True/False): is this a contracted braille table (True) or uncontracted (False).
  • output (True/False): the table can be listed in output table list in NVDA's braille settings.
  • input (True/False): braille can be entered using this table and listed in input table list in NVDA's braille settings.

Note: you must fill out this dictionary if at least one custom braille table is included in the add-on. If not, leave the dictionary empty.

To manage documentation files for your addon:

1. Copy the readme.md file for your add-on to the first created folder, where you copied buildVars.py. You can also copy style.css to improve the presentation of HTML documents.
2. Documentation files (named readme.md) must be placed into addon\doc\<lang>/.

To package the add-on for distribution:

1. Open a command line, change to the folder that has the sconstruct file (usually the root of your add-on development folder) and run the scons command. The created add-on, if there were no errors, is placed in the current directory.
2. You can further customize variables in the buildVars.py file.
3. You can also customize version and update channel information from command line by passing the following switches when running scons:
   • version: add-on version string.
   • versionNumber: add-on version number of the form major.minor.patch (all integers)
   • channel: update channel (do not use this switch unless you know what you are doing).
   • dev: suitable for development builds, names the add-on according to current date (yyyymmdd) and sets update channel to "dev".

Additional tools

The template includes configuration files for use with additional tools such as linters. These include:

• Flake8 (flake8.ini): a Python code linter (3.7.9 or later, can be installed with PIP).

Read the documentation for the tools you wish to use when building and developing add-ons.

Note that this template only provides a basic add-on structure and build infrastructure. You may need to adapt it for your specific needs such as using additional tools.

If you have any issues please use the NVDA addon list mentioned above.

addontemplate's Issues

Add support for custom braille translation tables

Hi,

With nvaccess/nvda#3304 implemented (NVDA 2024.3), it becomes possible to define and include custom braille translation tables as an add-on or included with other add-ons. With this, an add-on author can ship a Liblouis compatible braille table.

The manifest format resembles nested dictionaries:

• A key named "brailleTables" houses custom braille translation tables.
• Each custom table is a key within the dictionary, with file name as the key.
• The braille table (key) entry has four fields: displayName (description), contracted (contracted (True) or uncontracted (False) braille code), input (available from input table list), output (shown in output table list).

The challenge here is allowing localized display name for braille tables - this is no longer a top-level manifest key, so manifest translation template must be edited.

Thanks (NVDA feature implementation by @LeonarddeR).

Doc style sheet: Remove inverted color scheme

The provided style.css sets an inverted color scheme on the generated HTML documentations (white writing on black background).

While such a color scheme is preferred for many low vision individuals (including myself), many other have different needs.
Strong contrast scheming should be the result of the user configuration of its computer, applications or magnification software - and not enforced by a document.
The default configuration for Windows and a large majority of applications (including the GUI of NVDA) is dark writing on a light background. If a user has specific needs, it already has to deal with configuration and specialized software.
Imposing an inverted color scheme on a document defeats the inverted color scheme setting on magnification software, resulting in specifically annoying the very users it misleadingly tried to help.

My opinion is that most accessible documents should not impose color scheme at all, thus allowing users to more easily apply any desired settings on their display.

Please consider removing the inverted color scheme on the documentation style sheet, which would be more consistent with the documentation shipped with NVDA.

PR follows.

Workflow failed to build

I cloned this project and applied it to my NVDA Addon, and enabled the workflow, I received an error notification after git push --tags.

File "/home/runner/work/virtualKeyboard/virtualKeyboard/sconstruct", line 213
result_brailleTables.append(f"displayName = {buildVars.brailleTables[table]["displayName"]}")
SyntaxError: f-string: unmatched '['
Error: Process completed with exit code 2.

This statement works fine on my local Windows platform, I don't know why it reports an error here. Anyway, I fixed the above error. I received another error notification after git push --tags.

scons: Reading SConscript files ...
Python 3.10 or greater required, but you have Python 3.9.19
Error: Process completed with exit code 2.

After fixing the above error, the NVDA Addon built correctly.

In summary, the specific suggestions for modification are as follows:

In the build_addon.yml file
python-version: 3.9
It is recommended to change to
python-version: 3.11

In the sconstruct file
result_brailleTables.append(f"displayName = {buildVars.brailleTables[table]["displayName"]}")
It is recommended to change to
result_brailleTables.append(f"displayName = {buildVars.brailleTables[table]['displayName']}")

These are just a few minor modifications, I have already modified them, and I would be happy to submit a PR to fix this issue.

Prepare the JSON generation for NV Access add-on datastore

Hi,

As NV Access is looking into add-on store proposal, and since some add-ons were registered on the NV Access datastore, it makes sense to prepare the add-ons community by offering a way to generate needed data for the add-on store entry. The store entry is a JSON file that records add-on name/ID, author, version, update channel, SHA256 hash, among other data. Therefore, at the template level, edit SConstruct to generate a template JSON file which must be filled in by authors once add-on package generation completes (some values may require manual editing such as version major.minor.patch/publisher, etc.).

This will be done in the following steps:

1. Enhanced buildVars.py by including fields such as license.
2. Edit SConstruct to generate a template JSON file named the same as add-on package name.

Thanks.

Remove the generation of the Json

When building the add-on, a Json file is generated.

It was useful when the add-on store submission process required it. But now, the submission process only requires to open an issue with an URL pointing to the .nvda-addon file and the generation of the Json is done transparently by the store submission process.

I recommend to remove the generation of the Json from the scons default target. It's up to you if you want to generate the whole code for Json generation or if you want to keep it. But if you keep it, please add a separate target to generate only the .json file, e.g. "scons json"

It's also worth noting that the json is not deleted when running "scons -c".

Adding a backslash before <lang> in the paths for localization and documentation files

Right now there isn't a backslash before the placeholder to show that the language code needs to be a folder. So the user may write, for instance, addon\localees\LC_MESSAGES\nvda.po instead of addon\locale\es\LC_MESSAGES\nvda.po. I actually did that mistake, although I had my doubts.

SConstruct: modernize syntax and require Python 3.11 as minimum version

Hi,

To be implemented around NVDA 2024.1 release:

I propose modernizing SConstruct file in add-on template to use:

• Formatted string literals (f strings) in places where string interpolations (%s) and str.format are used (unless this introduces security problems)
• Assignment expressions in places where variables are assigned and then used

Also, mark Python 3.11 as the minimum version to run SConstruct.

Thanks,

Enable markdown extensions

There are some handy markdown extensions available which can improve the quality of documentation. I propose enabling the following extensions by default;

• markdown.extensions.extra
• markdown.extensions.smarty
• markdown.extensions.toc

.gitignore: Ignore .pyo files

Please consider adding .pyo files to .gitignore.

PR follows.

Broken link in buildVars.py comment

The file mentions, in a comment, the link:
https://bitbucket.org/nvdaaddonteam/todo/raw/master/guidelines.txt
However the link is obsolete.
I was forwarded to: https://github.com/nvdaaddons/DevGuide

MD to HTML: documentation header does not reflect correct version if custom version is specified form command line

Hi,

Consider the following: an add-on author uses "scons version+something" to specify a custom version of the add-on. At least manifest records the correct version, but documentation doesn't.

Cause: buildVars map isn't updated to use version specified from command line, as documentation title will use add-on version recored in there.

Thanks.

Include `pgettext` calls when extracting translatable string literals

Unlike the NVDA build process, the addon template build process extracts translatable string literals only from calls to _ (underscore mapped to gettext), ignoring calls to pgettext (context-aware translation).

Please consider including calls to pgettext as well when extracting translatable string literals.

PR follows.

Support separate technical and user documentations

The current build process takes the root readme.md as the source for the user documentation.
While this is perfectly fine for simpler addons, more complex projects might be better fitted with separate technical and user documentations.

Please consider supporting optionally separating technical and user documentations.

PR follows.

E402 should be ignored in flake8.ini

E402 (which is for "module level import not at top of file") should be added to the ignored list in flake8.ini.

because it is common to import external libraries like this,

import os
import sys

sys.path.insert(0, os.path.join(os.path.dirname(__file__), "site-packages"))
from . import languages as languages

This causes E402 error, and there isn't really other way to use external libraries within nvda add-ons