Merge 26fc382 into 6b01449

seanbudd · web-flow · commit a9b60ce42875 · 2024-01-10T04:29:48.000Z
diff --git a/projectDocs/dev/userGuideStandards.md b/projectDocs/dev/userGuideStandards.md
@@ -23,7 +23,7 @@ Once the anchor is set it cannot be updated, while settings may move categories.
 
 || Options | Default (Enabled), Enabled, Disabled |
 || Default | Enabled |
-|| Toggle command | ``nvda+shift+e`` |
+|| Toggle command | ``NVDA+shift+e`` |
 
 || Option || Behaviour ||
 | Enabled | behaviour of enabled |
@@ -32,3 +32,68 @@ Once the anchor is set it cannot be updated, while settings may move categories.
 This setting allows the feature of using functionality in a certain situation to be controlled in some way.
 If necessary, a description of a common use case that is supported by each option.
 ```
+
+## Generation of Key Commands
+Generation of the Key Commands document requires certain commands to be included in the User Guide.
+These commands must begin at the start of the line and take the form:
+
+```t2t
+%kc:command: arg
+```
+
+The title command must appear first.
+The other commands are used to select content containing key commands to be included into the key commands document.
+Appropriate headings from the User Guide will be included implicitly.
+
+### Specifying the title
+The `kc:title` command must appear first and specifies the title of the Key Commands document.
+
+For example:
+```t2t
+%kc:title: NVDA Key Commands
+```
+
+### Selecting blocks
+
+The `kc:beginInclude` command begins a block of text which should be included verbatim.
+The block ends at the `kc:endInclude` command.
+
+For example:
+
+```t2t
+%kc:beginInclude
+|| Name | Desktop command | Laptop command | Description |
+...
+%kc:endInclude
+```
+
+### Headers for settings sections
+
+The `kc:settingsSection` command indicates the beginning of a section documenting individual settings.
+It specifies the header row for a table summarising the settings indicated by the `kc:setting` command (see below).
+In order, it must consist of a name column, a column for each keyboard layout and a description column.
+
+For example:
+```t2t
+%kc:settingsSection: || Name | Desktop command | Laptop command | Description |
+```
+
+### Including a setting
+
+The `kc:setting` command indicates a section for an individual setting.
+
+It must be followed by:
+
+* A heading containing the name of the setting;
+* A table row for each keyboard layout, or if the key is common to all layouts, a single line of text specifying the key after a colon;
+* A blank line; and
+* A line describing the setting.
+
+For example:
+```t2t
+%kc:setting
+==== Braille Tethered To ====
+| Desktop command | ``NVDA+control+t`` |
+| Laptop Command | ``NVDA+control+t`` |
+This option allows you to choose whether the braille display will follow the system focus, or whether it follows the navigator object / review cursor.
+```
diff --git a/site_scons/site_tools/md2html.py b/site_scons/site_tools/md2html.py
@@ -116,7 +116,7 @@ def md2html_actionFunc(
 
 	extensions = set(DEFAULT_EXTENSIONS)
 	if isKeyCommands:
-		from keyCommandsDoc import KeyCommandsExtension
+		from user_docs.keyCommandsDoc import KeyCommandsExtension
 		extensions.add(KeyCommandsExtension())
 
 	markdown.markdownFromFile(
@@ -146,7 +146,7 @@ def exists(env: SCons.Environment.Environment) -> bool:
 		"markdown_link_attr_modifier",
 		"mdx_truly_sane_lists",
 		"mdx_gh_links",
-		"keyCommandsDoc",
+		"user_docs.keyCommandsDoc",
 	]:
 		if find_spec(ext) is None:
 			return False
diff --git a/site_scons/site_tools/t2t.py b/site_scons/site_tools/t2t.py
@@ -12,7 +12,7 @@ def txt2tags_actionFunc(
 		env: SCons.Environment.Environment
 ):
 	import txt2tags
-	from keyCommandsDoc import Command
+	from user_docs.keyCommandsDoc import Command
 
 	with open(source[0].path, "r", encoding="utf-8") as mdFile:
 		mdOriginal = mdFile.read()
diff --git a/user_docs/keyCommandsDoc.py b/user_docs/keyCommandsDoc.py
@@ -0,0 +1,259 @@
+# -*- coding: UTF-8 -*-
+# A part of NonVisual Desktop Access (NVDA)
+# Copyright (C) 2010-2024 NV Access Limited, Mesar Hameed, Takuya Nishimoto
+# This file is covered by the GNU General Public License.
+# See the file COPYING for more details.
+
+"""
+Generates the Key Commands document from the User Guide.
+Works as a Python Markdown Extension:
+https://python-markdown.github.io/extensions/
+
+Refer to user guide standards for more information on syntax rules:
+https://github.com/nvaccess/nvda/blob/master/projectDocs/dev/userGuideStandards.md
+"""
+
+from enum import auto, Enum, IntEnum, StrEnum
+import re
+from collections.abc import Iterator
+
+from markdown import Extension, Markdown
+from markdown.preprocessors import Preprocessor
+
+
+LINE_END = "\r\n"
+
+
+class Section(IntEnum):
+	"""Sections must be nested in this order."""
+	HEADER = auto()
+	BODY = auto()
+
+
+class Command(StrEnum):
+	TITLE = "title"
+	BEGIN_INCLUDE = "beginInclude"
+	END_INCLUDE = "endInclude"
+	SETTING = "setting"
+	SETTINGS_SECTION = "settingsSection"
+
+	def t2tRegex(self) -> re.Pattern:
+		return re.compile(rf"%kc:({self.value}.*)")
+
+
+class Regex(Enum):
+	COMMAND = re.compile(r"^<!-- KC:(?P<cmd>[^:\s]+)(?:: (?P<arg>.*))? -->$")
+	HEADING = re.compile(r"^(?P<id>#+)(?P<txt>.*)$")
+	SETTING_SINGLE_KEY = re.compile(r"^[^|]+?[:：]\s*(.+?)\s*$")
+	TABLE_ROW = re.compile(r"^(\|.*\|)$")
+
+
+class KeyCommandsError(Exception):
+	"""Raised due to an error encountered in the User Guide related to generation of the Key Commands document.
+	"""
+
+
+class KeyCommandsExtension(Extension):
+	# Magic number, priorities are not well documented.
+	# It's unclear what the range of priorities are to compare to, but 25 seems to work, 1 doesn't.
+	# See https://python-markdown.github.io/extensions/api/#registries
+	PRIORITY = 25
+
+	def extendMarkdown(self, md: Markdown):
+		md.preprocessors.register(KeyCommandsPreprocessor(md), 'key_commands', self.PRIORITY)
+
+
+class KeyCommandsPreprocessor(Preprocessor):
+	def __init__(self, md: Markdown | None):
+		super().__init__(md)
+		self.initialize()
+
+	def initialize(self):
+		self._ugLines: Iterator[str] = iter(())
+		self._kcLines: list[str] = []
+		#: The current section of the key commands file.
+		self._kcSect: Section = Section.HEADER
+		#: The current stack of headings.
+		self._headings: list[re.Match] = []
+		#: The 0 based level of the last heading in L{_headings} written to the key commands file.
+		self._kcLastHeadingLevel: int = -1
+		#: Whether lines which aren't commands should be written to the key commands file as is.
+		self._kcInclude: bool = False
+		#: The header row for settings sections.
+		self._settingsHeaderRow: str | None = None
+		#: The number of layouts for settings in a settings section.
+		self._settingsNumLayouts: int = 0
+		#: The current line number being processed, used to present location of syntax errors
+		self._lineNum: int = 0
+		# We want to skip the title line to replace it with the KC:TITLE command argument.
+		self._skippedTitle = False
+
+	def run(self, lines: list[str]) -> list[str]:
+		# Turn this into an iterator so we can use next() to seek through lines.
+		self._ugLines = iter(lines)
+		for line in self._ugLines:
+			line = line.strip()
+			self._lineNum += 1
+
+			# We want to skip the title line to replace it with the KC:TITLE command argument.
+			if line.startswith("# ") and not self._skippedTitle:
+				self._skippedTitle = True
+				continue
+
+			m = Regex.COMMAND.value.match(line)
+			if m:
+				self._command(**m.groupdict())
+				continue
+
+			m = Regex.HEADING.value.match(line)
+			if m:
+				self._heading(m)
+				continue
+
+			if self._kcInclude:
+				self._kcLines.append(line)
+
+		return self._kcLines.copy()
+
+	def _command(self, cmd: Command | None = None, arg: str | None = None):
+		# Handle header commands.
+		if cmd == Command.TITLE.value:
+			if self._kcSect > Section.HEADER:
+				raise KeyCommandsError(f"{self._lineNum}, title command is not valid here")
+			# Write the title and two blank lines to complete the txt2tags header section.
+			self._kcLines.append("# " + arg + LINE_END * 2)
+			self._kcSect = Section.BODY
+			return
+
+		elif self._kcSect == Section.HEADER:
+			raise KeyCommandsError(f"{self._lineNum}, title must be the first command")
+
+		if cmd == Command.BEGIN_INCLUDE.value:
+			self._writeHeadings()
+			self._kcInclude = True
+		elif cmd == Command.END_INCLUDE.value:
+			self._kcInclude = False
+			self._kcLines.append("")
+
+		elif cmd == Command.SETTINGS_SECTION.value:
+			# The argument is the table header row for the settings section.
+			# Replace t2t header syntax with markdown syntax.
+			self._settingsHeaderRow = arg.replace("||", "|")
+			# There are name and description columns.
+			# Each of the remaining columns provides keystrokes for one layout.
+			# There's one less delimiter than there are columns, hence subtracting 1 instead of 2.
+			self._settingsNumLayouts = arg.strip("|").count("|") - 1
+			if self._settingsNumLayouts < 1:
+				raise KeyCommandsError(
+					f"{self._lineNum}, settingsSection command must specify the header row for a table"
+					" summarising the settings"
+				)
+
+		elif cmd == Command.SETTING.value:
+			self._handleSetting()
+
+		else:
+			raise KeyCommandsError(f"{self._lineNum}, Invalid command {cmd}")
+
+	def _seekNonEmptyLine(self) -> str:
+		"""Seeks to the next non-empty line in the user guide.
+		"""
+		line = next(self._ugLines).strip()
+		self._lineNum += 1
+		while not line:
+			try:
+				line = next(self._ugLines).strip()
+			except StopIteration:
+				return line
+			self._lineNum += 1
+		return line
+
+	def _areHeadingsPending(self) -> bool:
+		return self._kcLastHeadingLevel < len(self._headings) - 1
+
+	def _writeHeadings(self):
+		level = self._kcLastHeadingLevel + 1
+		# Only write headings we haven't yet written.
+		for level, heading in enumerate(self._headings[level:], level):
+			self._kcLines.append(heading.group(0))
+		self._kcLastHeadingLevel = level
+
+	def _heading(self, m: re.Match):
+		# We work with 0 based heading levels.
+		level = len(m.group("id")) - 1
+		try:
+			del self._headings[level:]
+		except IndexError:
+			pass
+		self._headings.append(m)
+		self._kcLastHeadingLevel = min(self._kcLastHeadingLevel, level - 1)
+
+	def _handleSetting(self):
+		if not self._settingsHeaderRow:
+			raise KeyCommandsError("%d, setting command cannot be used before settingsSection command" % self._lineNum)
+
+		if self._areHeadingsPending():
+			# There are new headings to write.
+			# If there was a previous settings table, it ends here, so write a blank line.
+			self._kcLines.append("")
+			self._writeHeadings()
+			# New headings were written, so we need to output the header row.
+			self._kcLines.append(self._settingsHeaderRow)
+			numCols = self._settingsNumLayouts + 2  # name + description + layouts
+			self._kcLines.append("|" + "---|" * numCols)
+
+		# The next line should be a heading which is the name of the setting.
+		line = self._seekNonEmptyLine()
+		m = Regex.HEADING.value.match(line)
+		if not m:
+			raise KeyCommandsError(f"{self._lineNum}, setting command must be followed by heading")
+		name = m.group("txt")
+
+		# The next few lines should be table rows for each layout.
+		# Alternatively, if the key is common to all layouts, there will be a single line of text specifying the key after a colon.
+		keys: list[str] = []
+		for _layout in range(self._settingsNumLayouts):
+			line = self._seekNonEmptyLine()
+
+			m = Regex.SETTING_SINGLE_KEY.value.match(line)
+			if m:
+				keys.append(m.group(1))
+				break
+			elif not Regex.TABLE_ROW.value.match(line):
+				raise KeyCommandsError(
+					f"{self._lineNum}, setting command: "
+					"There must be one table row for each keyboard layout"
+				)
+
+			# This is a table row.
+			# The key will be the second column.
+			try:
+				key = line.strip("|").split("|")[1].strip()
+			except IndexError:
+				raise KeyCommandsError(f"{self._lineNum}, setting command: Key entry not found in table row.")
+			else:
+				keys.append(key)
+
+		if 1 == len(keys) < self._settingsNumLayouts:
+			# The key has only been specified once, so it is the same in all layouts.
+			key = keys[0]
+			keys[1:] = (key for _layout in range(self._settingsNumLayouts - 1))
+
+		# There should now be a blank line.
+		line = next(self._ugLines).strip()
+		self._lineNum += 1
+		if line:
+			raise KeyCommandsError(
+				f"{self._lineNum}, setting command: The keyboard shortcuts must be followed by a blank line. "
+				"Multiple keys must be included in a table. "
+				f"Erroneous key: {key}"
+			)
+
+		# Finally, the next line should be the description.
+		desc = self._seekNonEmptyLine()
+		self._kcLines.append(f"| {name} | {' | '.join(keys)} | {desc} |")
+		if not self._kcLines[-2].startswith("|"):
+			# The previous line was not a table, so this is a new table.
+			# Write the header row.
+			numCols = len(keys) + 2  # name + description + layouts
+			self._kcLines.append("|" + "---|" * numCols)
