Initial commit

.gitattributes

@@ -0,0 +1,8 @@
+# Set default behaviour, in case users don't have core.autocrlf set.
+* text=auto
+
+# Try to ensure that po files in the repo does not include
+# source code line numbers.
+# Every person expected to commit po files should change their personal config file as described here:
+# https://mail.gnome.org/archives/kupfer-list/2010-June/msg00002.html
+*.po filter=cleanpo

.gitignore

@@ -0,0 +1,10 @@
+addon/doc/*.css
+addon/doc/en/
+*_docHandler.py
+*.html
+*.ini
+*.mo
+*.pot
+*.py[co]
+*.nvda-addon
+.sconsign.dblite

buildVars.py

@@ -0,0 +1,73 @@
+# -*- coding: UTF-8 -*-
+
+# Build customizations
+# Change this file instead of sconstruct or manifest files, whenever possible.
+
+
+# Since some strings in `addon_info` are translatable,
+# we need to include them in the .po files.
+# Gettext recognizes only strings given as parameters to the `_` function.
+# To avoid initializing translations in this module we simply roll our own "fake" `_` function
+# which returns whatever is given to it as an argument.
+def _(arg):
+	return arg
+
+
+# Add-on information variables
+addon_info = {
+	# add-on Name/identifier, internal for NVDA
+	"addon_name": "addonTemplate",
+	# Add-on summary, usually the user visible name of the addon.
+	# Translators: Summary for this add-on
+	# to be shown on installation and add-on information found in Add-ons Manager.
+	"addon_summary": _("Add-on user visible name"),
+	# Add-on description
+	# Translators: Long description to be shown for this add-on on add-on information from add-ons manager
+	"addon_description": _("""Description for the add-on.
+It can span multiple lines."""),
+	# version
+	"addon_version": "x.y",
+	# Author(s)
+	"addon_author": "name <[email protected]>",
+	# URL for the add-on documentation support
+	"addon_url": None,
+	# Documentation file name
+	"addon_docFileName": "readme.html",
+	# Minimum NVDA version supported (e.g. "2018.3.0", minor version is optional)
+	"addon_minimumNVDAVersion": None,
+	# Last NVDA version supported/tested (e.g. "2018.4.0", ideally more recent than minimum version)
+	"addon_lastTestedNVDAVersion": None,
+	# Add-on update channel (default is None, denoting stable releases,
+	# and for development releases, use "dev".)
+	# Do not change unless you know what you are doing!
+	"addon_updateChannel": None,
+}
+
+# Define the python files that are the sources of your add-on.
+# You can either list every file (using ""/") as a path separator,
+# or use glob expressions.
+# For example to include all files with a ".py" extension from the "globalPlugins" dir of your add-on
+# the list can be written as follows:
+# pythonSources = ["addon/globalPlugins/*.py"]
+# For more information on SCons Glob expressions please take a look at:
+# https://scons.org/doc/production/HTML/scons-user/apd.html
+pythonSources = []
+
+# Files that contain strings for translation. Usually your python sources
+i18nSources = pythonSources + ["buildVars.py"]
+
+# Files that will be ignored when building the nvda-addon file
+# Paths are relative to the addon directory, not to the root directory of your addon sources.
+excludedFiles = []
+
+# Base language for the NVDA add-on
+# If your add-on is written in a language other than english, modify this variable.
+# For example, set baseLanguage to "es" if your add-on is primarily written in spanish.
+baseLanguage = "en"
+
+# Markdown extensions for add-on documentation
+# Most add-ons do not require additional Markdown extensions.
+# If you need to add support for markup such as tables, fill out the below list.
+# Extensions string must be of the form "markdown.extensions.extensionName"
+# e.g. "markdown.extensions.tables" to add tables.
+markdownExtensions = []

manifest-translated.ini.tpl

@@ -0,0 +1,2 @@
+summary = "{addon_summary}"
+description = """{addon_description}"""

manifest.ini.tpl

@@ -0,0 +1,10 @@
+name = {addon_name}
+summary = "{addon_summary}"
+description = """{addon_description}"""
+author = "{addon_author}"
+url = {addon_url}
+version = {addon_version}
+docFileName = {addon_docFileName}
+minimumNVDAVersion = {addon_minimumNVDAVersion}
+lastTestedNVDAVersion = {addon_lastTestedNVDAVersion}
+updateChannel = {addon_updateChannel}

readme.md

@@ -0,0 +1,74 @@
+# 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](https://github.com/nvdaaddons/DevGuide/wiki/NVDA-Add-on-Development-Guide).
+The NVDA add-on development/discussion list [is here](https://nvda-addons.groups.io/g/nvda-addons)
+
+Copyright (C) 2012-2021 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.
+
+## 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.
+* 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. A **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.
+
+## Requirements
+
+You need the following software to use this code for your NVDA add-on development and packaging:
+
+* a Python distribution (3.7 or later is recommended). Check the [Python Website](https://www.python.org) for Windows Installers.
+* Scons - [Website](https://www.scons.org/) - version 3.1.0 or later. You can instlal 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](https://gnuwin32.sourceforge.net/downlinks/gettext.php).
+* Markdown 3.1.0 or later, if you want to convert documentation files to HTML documents. You can install it via PIP.
+
+## 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 **site_scons** folder, and the following files, into your new empty folder: **buildVars.py**, **manifest.ini.tpl**, **manifest-translated.ini.tpl**, **sconstruct**, **.gitignore**, and **.gitattributes**
+3. Create an **addon** folder inside your new folder. Inside the **addon* folder, create needed folders for the add-on modules (e.g. appModules, synthDrivers, etc.). An add-on may have one or more module folders.
+4. In the **buildVars.py** file, change variable **addon_info** with your add-on's information (name, summary, description, version, author and url).
+5. Put your code in the usual folders for NVDA extension, under the **addon** folder. For instance: globalPlugins, synthDrivers, etc.
+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).
+* Summary (string): name as shown on NVDA's Add-ons Manager.
+* Description (string): a short detailed description about the add-on.
+* Version (string)
+* 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 (typically community add-ons website address (https://addons.nvda-project.org) is used).
+* 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.
+
+### 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.
+	* 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".
+
+Note that this template only provides a basic add-on structure and build infrastructure. You may need to adapt it for your specific needs.
+
+If you have any issues please use the NVDA addon list mentioned above.