nvdaaddons/addontemplate

Template and metadata used by NVDA community add-ons

addontemplate's Issues

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".

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,

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.

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

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).

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.

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.

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

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.

.gitignore: Ignore .pyo files

Please consider adding .pyo files to .gitignore.

PR follows.

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

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.

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.