Create command to display Ada & SPARK user's guide

This command uses Microsoft's Live Preview extension, which
we propose to download automatically via our extension pack.

For eng/ide/ada_language_server#1705

Author: AnthonyLeonardoGracio

CHANGELOG.md

@@ -4,6 +4,7 @@
 section below it for the last release. -->
 ## \<next>
 
+* Add `Ada: Open User's Guide` command displaying the HTML version of the Ada & SPARK extension User's Guide using Microsoft's Live Preview extension
 * New refactoring: [Extract Variable](https://github.com/AdaCore/ada_language_server/blob/master/doc/refactoring_tools.md#extract-variable)
 * Added a `Ada: Report Issue` command that opens the [VS Code Issue Reporter](https://code.visualstudio.com/docs/supporting/FAQ#_report-an-issue-with-a-vs-code-extension) with an extension-specific template
 * `Go to Definition` now jumps respectively on the `begin`, `private` and `body` keywords

integration/vscode/ada/package.json

@@ -14,7 +14,8 @@
     ],
     "extensionPack": [
         "ms-vscode.cpptools",
-        "ms-sarifvscode.sarif-viewer"
+        "ms-sarifvscode.sarif-viewer",
+        "ms-vscode.live-server"
     ],
     "activationEvents": [
         "workspaceContains:*.gpr",
@@ -1145,6 +1146,11 @@
                 "title": "Add subprogram box",
                 "category": "Ada"
             },
+            {
+                "command": "ada.openUsersGuide",
+                "title": "Open User's Guide",
+                "category": "Ada"
+            },
             {
                 "command": "ada.showExtensionOutput",
                 "title": "Show extension output",

integration/vscode/ada/src/commands.ts

@@ -14,6 +14,7 @@ import {
     CMD_BUILD_AND_RUN_MAIN,
     CMD_GPR_PROJECT_ARGS,
     CMD_RESTART_LANG_SERVERS,
+    CMD_OPEN_USERS_GUIDE,
     CMD_SHOW_ADA_LS_OUTPUT,
     CMD_SHOW_EXTENSION_LOGS,
     CMD_SHOW_GPR_LS_OUTPUT,
@@ -22,11 +23,18 @@ import {
     CMD_SPARK_LIMIT_REGION_ARG,
     CMD_SPARK_LIMIT_SUBP_ARG,
     CMD_SPARK_PROVE_SUBP,
+    VSCODE_UG_LIVE_DOC_URL,
 } from './constants';
 import { AdaConfig, getOrAskForProgram, initializeConfig } from './debugConfigProvider';
 import { adaExtState, logger, mainOutputChannel } from './extension';
 import { loadGnatCoverageReport } from './gnattest';
-import { findAdaMain, getProjectFileRelPath, getSymbols } from './helpers';
+import {
+    findAdaMain,
+    getProjectFileRelPath,
+    getSymbols,
+    isExtensionInstalled,
+    isRunningOnRemote,
+} from './helpers';
 import { registerSPARKTaskWrappers } from './sparkCommands';
 import { askSPARKOptions, getLastSPARKOptions } from './sparkOptionsPicker';
 import {
@@ -96,6 +104,9 @@ export function registerCommands(context: vscode.ExtensionContext, clients: Exte
     context.subscriptions.push(
         vscode.commands.registerCommand('ada.subprogramBox', addSubprogramBoxCommand),
     );
+    context.subscriptions.push(
+        vscode.commands.registerCommand(CMD_OPEN_USERS_GUIDE, openUsersGuide),
+    );
     context.subscriptions.push(
         vscode.commands.registerCommand(CMD_SHOW_EXTENSION_LOGS, () => mainOutputChannel.show()),
     );
@@ -192,6 +203,117 @@ export function registerCommands(context: vscode.ExtensionContext, clients: Exte
     registerSPARKTaskWrappers(context);
 }
 
+/**
+ * Get the extension user's guide URI, if it exists on disk.
+ *
+ * @returns the URI of the extension user's guide, or `null` if the file
+ * does not exist.
+ */
+export function getUsersGuideURI(): vscode.Uri | null {
+    const ug_path = vscode.Uri.joinPath(
+        adaExtState.context.extensionUri,
+        'share',
+        'doc',
+        'als',
+        'html',
+        'users_guide',
+        'index.html',
+    );
+
+    if (existsSync(ug_path.fsPath)) {
+        return ug_path;
+    }
+    return null;
+}
+
+/**
+ * Open the extension user's guide in a new editor tab using LivePreview
+ * if doable.
+ * This requires the "Live Preview" extension by Microsoft to be installed.
+ * The user will be warned if this extension is not installed or if the user's
+ * guide cannot be found on disk.
+ */
+async function openUsersGuide() {
+    const usersGuideURI = getUsersGuideURI();
+
+    // The user's guide is not found on disk, warn the user and propose
+    // to open the online documentation instead.
+    if (!usersGuideURI) {
+        async function showUGNotFoundError() {
+            const action = await vscode.window.showErrorMessage(
+                "The User's Guide was not found under the Ada & SPARK extension installation. " +
+                    'Please consult the online documentation instead.',
+                'Open Online Docs',
+            );
+            if (action === 'Open Online Docs') {
+                void vscode.env.openExternal(vscode.Uri.parse(VSCODE_UG_LIVE_DOC_URL));
+            }
+        }
+
+        void showUGNotFoundError();
+        return;
+    }
+
+    //  Live Preview extension is not installed, warn the user and propose
+    //  to open the user's guide with the default browser instead.
+    if (!isExtensionInstalled('ms-vscode.live-server')) {
+        /** Show the LivePreview extension's page in the marketplace
+         */
+        function showLivePreviewInMarketplace() {
+            void vscode.commands.executeCommand(
+                'workbench.extensions.search',
+                '@id:ms-vscode.live-server',
+            );
+        }
+
+        /** Show an error message proposing to install Live Preview or open the
+         * user's guide with the default browser instead.
+         */
+        async function showNotLivePreviewInstalledError() {
+            // If not running on a remote, propose to open the locally installed
+            // user's guide with the default browser instead.
+            if (!isRunningOnRemote()) {
+                const action = await vscode.window.showErrorMessage(
+                    "Microsoft's Live Preview extension is not installed. " +
+                        "Please install it to open the User's Guide directly in VS Code, " +
+                        'otherwise open it with your system browser.',
+                    'Install Live Preview',
+                    'Open in Browser',
+                );
+                if (action === 'Open in Browser') {
+                    if (usersGuideURI) {
+                        void vscode.env.openExternal(usersGuideURI);
+                    }
+                } else if (action === 'Install Live Preview') {
+                    showLivePreviewInMarketplace();
+                }
+            } else {
+                // If running on a remote, propose to install Live Preview or
+                // open the online documentation instead.
+                const action = await vscode.window.showErrorMessage(
+                    "Microsoft's Live Preview extension is not installed. " +
+                        "Please install it to open the User's Guide directly in VS Code " +
+                        'when connected to a remote machine, or consult ' +
+                        'the online documentation instead.',
+                    'Install Live Preview',
+                    'Open Online Docs',
+                );
+                if (action === 'Open Online Docs') {
+                    void vscode.env.openExternal(vscode.Uri.parse(VSCODE_UG_LIVE_DOC_URL));
+                } else if (action === 'Install Live Preview') {
+                    showLivePreviewInMarketplace();
+                }
+            }
+        }
+
+        void showNotLivePreviewInstalledError();
+        return;
+    }
+
+    // Open the user's guide using Live Preview
+    await vscode.commands.executeCommand('livePreview.start.internalPreview.atFile', usersGuideURI);
+}
+
 /**
  * Add a subprogram box above the subprogram enclosing the cursor's position, if any.
  *

integration/vscode/ada/src/constants.ts

@@ -5,17 +5,17 @@
  *
  * @see {@link buildAndRunSpecifiedMain}
  */
-
 export const CMD_BUILD_AND_RUN_MAIN = 'ada.buildAndRunMain';
+
 /**
  * Identifier for a hidden command used for building and debugging a project main.
  * The command accepts a parameter which is the URI of the main source file.
  * It is triggered by CodeLenses provided by the extension.
  *
  * @see {@link buildAndDebugSpecifiedMain}
  */
-
 export const CMD_BUILD_AND_DEBUG_MAIN = 'ada.buildAndDebugMain';
+
 /**
  * Identifier for a hidden command used for building and running a project main,
  * using GNATemulator.
@@ -24,8 +24,8 @@ export const CMD_BUILD_AND_DEBUG_MAIN = 'ada.buildAndDebugMain';
  *
  * @see {@link buildAndRunMainWithGNATemulator}
  */
-
 export const CMD_BUILD_AND_RUN_GNATEMULATOR = 'ada.buildAndRunGNATemulator';
+
 /**
  * Identifier for a hidden command used for building and debugging a project main,
  * using GNATemulator.
@@ -34,21 +34,20 @@ export const CMD_BUILD_AND_RUN_GNATEMULATOR = 'ada.buildAndRunGNATemulator';
  *
  * @see {@link buildAndDebugSpecifiedMain}
  */
-
 export const CMD_BUILD_AND_DEBUG_GNATEMULATOR = 'ada.buildAndDebugGNATemulator';
+
 /**
  * Identifier for a hidden command that returns an array of strings constituting
  * the -P and -X project and scenario arguments.
  */
-
 export const CMD_GPR_PROJECT_ARGS = 'ada.gprProjectArgs';
+
 /**
  * Identifier for a hidden command that returns a string referencing the current
  * project.  That string is either `"$\{config:ada.projectFile\}"` if that
  * setting is configured, or otherwise the full path to the project file
  * returned from a query to the
  */
-
 export const CMD_GET_PROJECT_FILE = 'ada.getProjectFile';
 
 export const CMD_SPARK_LIMIT_SUBP_ARG = 'ada.spark.limitSubpArg';
@@ -58,28 +57,38 @@ export const CMD_SPARK_ASK_OPTIONS = 'ada.spark.askGNATproveOptions';
 export const CMD_SPARK_CURRENT_GNATPROVE_OPTIONS = 'ada.spark.gnatproveOptions';
 
 /**
- * Identifier for the command that shows the extension's output in the Output panel.
+ * Identifier for the command that opens the extension's user's guide.
  */
+export const CMD_OPEN_USERS_GUIDE = 'ada.openUsersGuide';
 
+/**
+ * Identifier for the command that shows the extension's output in the Output panel.
+ */
 export const CMD_SHOW_EXTENSION_LOGS = 'ada.showExtensionOutput';
+
 /**
  * Identifier for the command that shows the output of the ALS for Ada in the Output panel.
  */
-
 export const CMD_SHOW_ADA_LS_OUTPUT = 'ada.showAdaLSOutput';
+
 /**
  * Identifier for the command that shows the output of the ALS for GPR in the Output panel.
  */
-
 export const CMD_SHOW_GPR_LS_OUTPUT = 'ada.showGprLSOutput';
+
 /**
  * Identifier for the command that reloads the currently loaded project on server-side.
  */
-
 export const CMD_RELOAD_PROJECT = 'als-reload-project';
+
 /**
  * Identifier for the command that restarts all the language servers spawned by the extension
  * (Ada and GPR).
  */
-
 export const CMD_RESTART_LANG_SERVERS = 'ada.restartLanguageServers';
+
+/**
+ * Live doc URL of the Ada & SPARK VS Code extension User's Guide.
+ */
+export const VSCODE_UG_LIVE_DOC_URL =
+    'https://docs.adacore.com/live/wave/als/html/als-doc/index.html';

integration/vscode/ada/src/extension.ts

@@ -39,6 +39,10 @@ import { activateE3TestsuiteIntegration } from './e3Testsuite';
 
 export const EXTENSION_NAME: string = meta.displayName;
 
+/** The context key that is set when the Ada extension has been
+ * activated. This can be used in `when` clauses in `package.json` to enable or
+ * disable commands, menu items, keybindings, etc.
+ */
 const ADA_CONTEXT = 'ADA_PROJECT_CONTEXT';
 
 /**

integration/vscode/ada/src/helpers.ts

@@ -120,6 +120,23 @@ export const TERMINAL_ENV_SETTING_NAME =
     'terminal.integrated.env.' +
     (platform() == 'darwin' ? 'osx' : platform() == 'win32' ? 'windows' : 'linux');
 
+/**
+ * Check if VS Code is running in a remote environment.
+ * @returns True if running remotely, false otherwise.
+ */
+export function isRunningOnRemote(): boolean {
+    return vscode.env.remoteName !== undefined;
+}
+
+/**
+ * Check if a VS Code extension is installed.
+ * @param extensionId - The ID of the extension to check.
+ * @returns True if the extension is installed, false otherwise.
+ */
+export function isExtensionInstalled(extensionId: string): boolean {
+    return vscode.extensions.getExtension(extensionId) !== undefined;
+}
+
 /**
  *
  * @returns the value of the applicable `terminal.integrated.env.*` setting,