Sync upstream AddonTemplate

.github/workflows/build_addon.yml

@@ -3,49 +3,69 @@ name: build addon
 on:
   push:
     tags: ["*"]
-    # To build on main/master branch, uncomment the following line:
-    # branches: [ main , master ]
+    branches: [ main , master ]
 
   pull_request:
     branches: [ main, master ]
 
   workflow_dispatch:
 
+env:
+  # Set this to "true" when source formatting should block pull requests,
+  # branch builds, and release builds.
+  SOURCE_FORMATTING_BLOCKS_BUILD: "false"
+
 jobs:
   build:
+    # Building the add-on template as an add-on does not make sense (and fails).
+    # Do not modify this repo name with your own one! (should remain the template)
+    if: github.repository != 'nvaccess/addonTemplate'
 
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v5
-
-    - run: echo -e "pre-commit\nscons\nmarkdown">requirements.txt
-
-    - name: Set up Python
-      uses: actions/setup-python@v6
+    - name: Checkout repo
+      uses: actions/checkout@v6
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
       with:
-        python-version: 3.11
-        cache: 'pip'
-
+        enable-cache: true
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip wheel
-        pip install -r requirements.txt
         sudo apt-get update  -y
         sudo apt-get install -y gettext
+        uv sync
 
-    - name: Code checks
-      run: export SKIP=no-commit-to-branch; pre-commit run --all
+    - name: Repository checks
+      run: |
+        export SKIP=no-commit-to-branch,pyright,trailing-whitespace,end-of-file-fixer,fix-byte-order-marker,check-vcs-permalinks,add-trailing-comma,ruff,ruff-format
+        uv run pre-commit run --all-files
+
+    - name: Source formatting
+      run: |
+        if ! uv run ruff format --check addon/globalPlugins/Access8Math tests buildVars.py; then
+          if [ "$SOURCE_FORMATTING_BLOCKS_BUILD" = "true" ]; then
+            exit 1
+          fi
+          echo "::warning::Source formatting check failed but SOURCE_FORMATTING_BLOCKS_BUILD is false."
+        fi
 
     - name: building addon
-      run: scons && scons pot
+      run: uv run scons && uv run scons pot
 
-    - uses: actions/upload-artifact@v5
+    - uses: actions/upload-artifact@v7
       with:
         name: packaged_addon
         path: |
           ./*.nvda-addon
+        archive: false
+
+    - uses: actions/upload-artifact@v7
+      with:
+        name: translation_template
+        path: |
           ./*.pot
+        archive: false
 
   upload_release:
     runs-on: ubuntu-latest
@@ -54,9 +74,12 @@ jobs:
     permissions:
       contents: write
     steps:
-    - uses: actions/checkout@v5
-    - name: download releases files
-      uses: actions/download-artifact@v6
+    - uses: actions/checkout@v6
+    - name: download all artifacts
+      uses: actions/download-artifact@v8
+      with:
+        path: .
+        merge-multiple: true
     - name: Display structure of downloaded files
       run: ls -R
     - name: Calculate sha256
@@ -65,7 +88,7 @@ jobs:
         sha256sum *.nvda-addon >> changelog.md
 
     - name: Release
-      uses: softprops/action-gh-release@v2
+      uses: softprops/action-gh-release@v3
       with:
         files: |
           *.nvda-addon

.gitignore

@@ -16,3 +16,4 @@ manifest.ini
 *.nvda-addon
 .sconsign.dblite
 /[0-9]*.[0-9]*.[0-9]*.json
+*.egg-info

.pre-commit-config.yaml

@@ -1,7 +1,87 @@
+# Copied from https://github.com/nvaccess/nvda
+# https://pre-commit.ci/
+# Configuration for Continuous Integration service
+ci:
+  # Pyright does not seem to work in pre-commit CI
+  skip: [pyright]
+  autoupdate_schedule: monthly
+  autoupdate_commit_msg: "Pre-commit auto-update"
+  autofix_commit_msg: "Pre-commit auto-fix"
+  submodules: true
+
+default_language_version:
+  python: python3.13
+
 repos:
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
-    hooks:
-      - id: check-ast
-      - id: check-case-conflict
-      - id: check-yaml
+- repo: https://github.com/pre-commit-ci/pre-commit-ci-config
+  rev: v1.6.1
+  hooks:
+    - id: check-pre-commit-ci-config
+
+- repo: meta
+  hooks:
+    # ensures that exclude directives apply to any file in the repository.
+    - id: check-useless-excludes
+    # ensures that the configured hooks apply to at least one file in the repository.
+    - id: check-hooks-apply
+
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+    # Prevents commits to certain branches
+    - id: no-commit-to-branch
+      args: ["--branch", "main", "--branch", "master", ]
+    # Checks that large files have not been added. Default cut-off for "large" files is 500kb.
+    - id: check-added-large-files
+    # Checks python syntax
+    - id: check-ast
+    # Checks for filenames that will conflict on case insensitive filesystems (the majority of Windows filesystems, most of the time)
+    - id: check-case-conflict
+    # Checks for artifacts from resolving merge conflicts.
+    - id: check-merge-conflict
+    # Checks Python files for debug statements, such as python's breakpoint function, or those inserted by some IDEs.
+    - id: debug-statements
+    # Removes trailing whitespace.
+    - id: trailing-whitespace
+      types_or: [python, c, c++, batch, markdown, toml, yaml, powershell]
+    # Ensures all files end in 1 (and only 1) newline.
+    - id: end-of-file-fixer
+      types_or: [python, c, c++, batch, markdown, toml, yaml, powershell]
+    # Removes the UTF-8 BOM from files that have it.
+    # See https://github.com/nvaccess/nvda/blob/master/projectDocs/dev/codingStandards.md#encoding
+    - id: fix-byte-order-marker
+      types_or: [python, c, c++, batch, markdown, toml, yaml, powershell]
+    # Validates TOML files.
+    - id: check-toml
+    # Validates YAML files.
+    - id: check-yaml
+    # Ensures that links to lines in files under version control point to a particular commit.
+    - id: check-vcs-permalinks
+    # Avoids using reserved Windows filenames.
+    - id: check-illegal-windows-names
+- repo: https://github.com/asottile/add-trailing-comma
+  rev: v3.2.0
+  hooks:
+  # Ruff preserves indent/new-line formatting of function arguments, list items, and similar iterables,
+  # if a trailing comma is added.
+  # This adds a trailing comma to args/iterable items in case it was missed.
+  - id: add-trailing-comma
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Matches Ruff version in pyproject.
+  rev: v0.12.7
+  hooks:
+    - id: ruff
+      name: lint with ruff
+      args: [ --fix ]
+    - id: ruff-format
+      name: format with ruff
+
+- repo: local
+  hooks:
+
+    - id: pyright
+      name: type check with pyright
+      entry: uv run pyright
+      language: system
+      types: [python]

.vscode/typings/__builtins__.pyi

@@ -1,6 +1,2 @@
-def _(msg: str) -> str:
-	...
-
-
-def pgettext(context: str, message: str) -> str:
-	...
+def _(msg: str) -> str: ...
+def pgettext(context: str, message: str) -> str: ...

buildVars.py

@@ -1,7 +1,7 @@
 # Build customizations
 # Change this file instead of sconstruct or manifest files, whenever possible.
 
-from site_scons.site_tools.NVDATool.typings import AddonInfo, BrailleTables, SymbolDictionaries
+from site_scons.site_tools.NVDATool.typings import AddonInfo, BrailleTables, SymbolDictionaries, SpeechDictionaries
 
 # Since some strings in `addon_info` are translatable,
 # we need to include them in the .po files.
@@ -21,7 +21,9 @@
 	addon_summary=_("Access8Math"),
 	# Add-on description
 	# Translators: Long description to be shown for this add-on on add-on information from add-on store
-	addon_description=_("""Allows access math content written by MathML ; Allows write math content by LaTeX"""),
+	addon_description=_(
+		"""Read MathML with speech and braille, explore expressions step by step, and write math in LaTeX."""
+	),
 	# version
 	addon_version="5.0",
 	# Brief changelog for this version
@@ -105,5 +107,14 @@
 # Each key is the name of the dictionary,
 # with keys inside recording the following attributes:
 # displayName (name of the speech dictionary shown to users and translatable),
-# mandatory (True when always enabled, False when not.
+# mandatory (True when always enabled, False when not).
 symbolDictionaries: SymbolDictionaries = {}
+
+# Custom speech dictionaries (distinct from symbol dictionaries above)
+# Speech dictionary files reside in the speechDicts folder and are named `name.dic`.
+# If your add-on includes custom speech (pronunciation) dictionaries (most will not), fill out this dictionary.
+# Each key is the name of the dictionary,
+# with keys inside recording the following attributes:
+# displayName (name of the speech dictionary shown to users and translatable),
+# mandatory (True when always enabled, False when not).
+speechDictionaries: SpeechDictionaries = {}

pyproject.toml

@@ -1,3 +1,49 @@
+[build-system]
+requires = ["setuptools~=80.9", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "Access8Math"
+dynamic = ["version"]
+description = "Read MathML with NVDA and write math in LaTeX"
+maintainers = [
+	{name = "Tseng Woody", email = "tsengwoody.tw@gmail.com"},
+]
+requires-python = ">=3.13,<3.14"
+classifiers = [
+	"Development Status :: 5 - Production/Stable",
+	"Intended Audience :: End Users/Desktop",
+	"License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)",
+	"Operating System :: Microsoft :: Windows",
+	"Programming Language :: Python :: 3",
+	"Topic :: Accessibility",
+]
+readme = "readme.md"
+license = {file = "COPYING.txt"}
+dependencies = [
+	# Build add-on
+	"scons==4.10.1",
+	"Markdown==3.10",
+	# Translations management
+	"requests==2.33.0",
+	"nh3==0.3.2",
+	"crowdin-api-client==1.24.1",
+	"lxml==6.1.0",
+	"mdx_truly_sane_lists==1.3",
+	"markdown-link-attr-modifier==0.2.1",
+	"mdx-gh-links==0.4",
+	# Lint
+	"uv==0.11.6",
+	"ruff==0.14.5",
+	"pre-commit==4.2.0",
+	"pyright[nodejs]==1.1.407",
+]
+[project.urls]
+Repository = "https://github.com/tsengwoody/Access8Math"
+
+[tool.setuptools]
+py-modules = []
+
 [tool.ruff]
 line-length = 110
 
@@ -20,10 +66,15 @@ include = [
 exclude = [
 	".git",
 	"__pycache__",
+	".venv",
+	"addon/globalPlugins/Access8Math/package",
+	"addon/runtime",
+	"buildVars.py",
 ]
 
 [tool.ruff.format]
 indent-style = "tab"
+line-ending = "lf"
 
 [tool.ruff.lint.mccabe]
 max-complexity = 15
@@ -33,13 +84,16 @@ ignore = [
 	# indentation contains tabs
 	"W191",
 ]
+logger-objects = ["logHandler.log"]
 
 [tool.ruff.lint.per-file-ignores]
-# sconstruct contains many inbuilt functions not recognised by the lint,
+# sconscripts contains many inbuilt functions not recognised by the lint,
 # so ignore F821.
 "sconstruct" = ["F821"]
 
 [tool.pyright]
+venvPath = ".venv"
+venv = "."
 pythonPlatform = "Windows"
 typeCheckingMode = "strict"
 
@@ -51,6 +105,8 @@ exclude = [
 	"sconstruct",
 	".git",
 	"__pycache__",
+	".venv",
+	"site_scons",
 	# When excluding concrete paths relative to a directory,
 	# not matching multiple folders by name e.g. `__pycache__`,
 	# paths are relative to the configuration file.
@@ -59,6 +115,7 @@ exclude = [
 # Tell pyright where to load python code from
 extraPaths = [
 	"./addon",
+	"../nvda/source",
 ]
 
 # General config
@@ -120,7 +177,6 @@ reportPropertyTypeMismatch = true
 reportRedeclaration = true
 reportReturnType = true
 reportSelfClsParameterName = true
-reportShadowedImports = true
 reportTypeCommentUsage = true
 reportTypedDictNotRequiredAccess = true
 reportUnboundVariable = true

sconstruct

@@ -61,6 +61,7 @@ env.Append(
 	addon_info=buildVars.addon_info,
 	brailleTables=buildVars.brailleTables,
 	symbolDictionaries=buildVars.symbolDictionaries,
+	speechDictionaries=buildVars.speechDictionaries,
 )
 
 if env["dev"]: