Report a user friendly message when the documentation is missing (#17052

)

When NVDA is run from source, if the documentation is missing, e.g. because it has not been built, there is a user friendly message indicating that the documentation is missing when using context help. Though, when trying to open the documentation from NVDA's menu, there is no user friendly message; there is only an error in the log.

Description of user facing changes
If the documentation is missing, a message pops up to report it to the user. In this case, we do not use ui.message as for context help, because the message is cut by the new focus being reported.

Description of development approach
Factored the function to report that the doc is missing.

Testing strategy:
Manual test, with and without built doc:
* Try to use context help
* NVDA menu -> Help: try to open User Guide, Key commands and Changes documentations.

source/documentationUtils.py

@@ -10,6 +10,11 @@
 import globalVars
 import languageHandler
 import NVDAState
+from logHandler import log
+import ui
+import queueHandler
+from gui.message import messageBox
+import wx
 
 
 def getDocFilePath(fileName: str, localized: bool = True) -> Optional[str]:
@@ -51,3 +56,20 @@ def getDocFilePath(fileName: str, localized: bool = True) -> Optional[str]:
 
 
 getDocFilePath.rootPath = None
+
+
+def reportNoDocumentation(fileName: str, useMsgBox: bool = False) -> None:
+	# Translators: Message reported upon action (e.g. context sensitive help, open documentation from NVDA menu)
+	noDocMessage = _("No documentation found.")
+	log.debugWarning(
+		f"Documentation not found ({fileName}): possible cause - running from source without building user docs.",
+	)
+	if useMsgBox:
+		messageBox(
+			noDocMessage,
+			# Translators: the title of an error message dialog
+			_("Error"),
+			wx.OK | wx.ICON_ERROR,
+		)
+	else:
+		queueHandler.queueFunction(queueHandler.eventQueue, ui.message, noDocMessage)

source/gui/__init__.py

@@ -13,7 +13,7 @@
 import globalVars
 import tones
 import ui
-from documentationUtils import getDocFilePath
+from documentationUtils import getDocFilePath, reportNoDocumentation
 from logHandler import log
 import config
 import versionInfo
@@ -737,13 +737,13 @@ def _appendHelpSubMenu(self, frame: MainFrame) -> None:
 		if not globalVars.appArgs.secure:
 			# Translators: The label of a menu item to open NVDA user guide.
 			item = self.helpMenu.Append(wx.ID_ANY, _("&User Guide"))
-			self.Bind(wx.EVT_MENU, lambda evt: os.startfile(getDocFilePath("userGuide.html")), item)
+			self.Bind(wx.EVT_MENU, lambda evt: self._openDocumentationFile("userGuide.html"), item)
 			# Translators: The label of a menu item to open the Commands Quick Reference document.
 			item = self.helpMenu.Append(wx.ID_ANY, _("Commands &Quick Reference"))
-			self.Bind(wx.EVT_MENU, lambda evt: os.startfile(getDocFilePath("keyCommands.html")), item)
+			self.Bind(wx.EVT_MENU, lambda evt: self._openDocumentationFile("keyCommands.html"), item)
 			# Translators: The label for the menu item to open What's New document.
 			item = self.helpMenu.Append(wx.ID_ANY, _("What's &new"))
-			self.Bind(wx.EVT_MENU, lambda evt: os.startfile(getDocFilePath("changes.html")), item)
+			self.Bind(wx.EVT_MENU, lambda evt: self._openDocumentationFile("changes.html"), item)
 
 			self.helpMenu.AppendSeparator()
 
@@ -792,6 +792,13 @@ def _appendHelpSubMenu(self, frame: MainFrame) -> None:
 		# Translators: The label for the Help submenu in NVDA menu.
 		self.menu.AppendSubMenu(self.helpMenu, _("&Help"))
 
+	def _openDocumentationFile(self, fileName: str) -> None:
+		helpFile = getDocFilePath(fileName)
+		if helpFile is None:
+			reportNoDocumentation(fileName, useMsgBox=True)
+			return
+		os.startfile(helpFile)
+
 	def _appendPendingUpdateSection(self, frame: MainFrame) -> None:
 		if not globalVars.appArgs.secure and updateCheck:
 			# installPendingUpdateMenuItemPos is later toggled based on if an update is available.

source/gui/contextHelp.py

@@ -40,13 +40,7 @@ def showHelp(helpId: str):
 		return
 	helpFile = documentationUtils.getDocFilePath("userGuide.html")
 	if helpFile is None:
-		# Translators: Message shown when trying to display context sensitive help,
-		# indicating that	the user guide could not be found.
-		noHelpMessage = _("No user guide found.")
-		log.debugWarning(
-			"No user guide found: possible cause - running from source without building user docs",
-		)
-		queueHandler.queueFunction(queueHandler.eventQueue, ui.message, noHelpMessage)
+		documentationUtils.reportNoDocumentation("userGuide.html")
 		return
 	log.debug(f"Opening help: helpId = {helpId}, userGuidePath: {helpFile}")