Merge b4102f2 into 4fbb634

npm/qsharp/src/compiler/compiler.ts

@@ -94,6 +94,7 @@ export interface ICompiler {
   ): Promise<CircuitData>;
 
   getDocumentation(): Promise<IDocFile[]>;
+  getCombinedDocumentation(): Promise<string>;
 
   checkExerciseSolution(
     userCode: string,
@@ -277,6 +278,22 @@ export class Compiler implements ICompiler {
     return this.wasm.generate_docs();
   }
 
+  async getCombinedDocumentation(): Promise<string> {
+    const docFiles: IDocFile[] = this.wasm.generate_docs();
+    // Create combined documentation in the worker
+    let content = "";
+    for (const file of docFiles) {
+      // Some files may contain information other than documentation
+      // For example, table of content is a separate file in a special format
+      // We check presence of qsharp.name in metadata to make sure we take
+      // only files that contain documentation from some qsharp object.
+      if (file.metadata.indexOf("qsharp.name:") >= 0) {
+        content += file.contents + "\n---\n";
+      }
+    }
+    return content;
+  }
+
   async checkExerciseSolution(
     userCode: string,
     exerciseSources: string[],
@@ -334,6 +351,7 @@ export const compilerProtocol: ServiceProtocol<ICompiler, QscEventData> = {
     getEstimates: "request",
     getCircuit: "request",
     getDocumentation: "request",
+    getCombinedDocumentation: "request",
     run: "requestWithProgress",
     checkExerciseSolution: "requestWithProgress",
   },

vscode/package.json

@@ -199,6 +199,10 @@
           "command": "qsharp-vscode.showCircuit",
           "when": "resourceLangId == qsharp"
         },
+        {
+          "command": "qsharp-vscode.showDocumentation",
+          "when": "resourceLangId == qsharp"
+        },
         {
           "command": "qsharp-vscode.setTargetProfile",
           "when": "resourceLangId == qsharp"
@@ -316,6 +320,11 @@
         "title": "Show circuit",
         "category": "Q#"
       },
+      {
+        "command": "qsharp-vscode.showDocumentation",
+        "title": "Show documentation",
+        "category": "Q#"
+      },
       {
         "command": "qsharp-vscode.workspacesRefresh",
         "category": "Q#",

vscode/src/documentation.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { IOperationInfo, getCompilerWorker } from "qsharp-lang";
+import { Uri } from "vscode";
+import { sendMessageToPanel } from "./webviewPanel";
+
+export async function showDocumentationCommand(
+  extensionUri: Uri,
+  _operation: IOperationInfo | undefined,
+) {
+  // Reveal panel an show 'Loading...' for immediate feedback.
+  sendMessageToPanel(
+    "documentationPanelType", // This is needed to route the message to the proper panel
+    true,
+    null,
+  );
+
+  // Get std library documentation from compiler.
+  const compilerWorkerScriptPath = Uri.joinPath(
+    extensionUri,
+    "./out/compilerWorker.js",
+  ).toString();
+  const worker = getCompilerWorker(compilerWorkerScriptPath);
+  const content = await worker.getCombinedDocumentation();
+
+  const message = {
+    command: "showDocumentationCommand", // This is handled in webview.tsx onMessage
+    contentToRender: content,
+  };
+
+  sendMessageToPanel(
+    "documentationPanelType", // This is needed to route the message to the proper panel
+    true,
+    message,
+  );
+}

vscode/src/webview/docview.tsx

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export function DocumentationView(props: {
+  renderer: (input: string) => string;
+  contentToRender: string;
+}) {
+  const renderedContent = {
+    __html: props.renderer(props.contentToRender),
+  };
+
+  return <div dangerouslySetInnerHTML={renderedContent} />;
+}

vscode/src/webview/webview.tsx

@@ -14,6 +14,7 @@ import {
   type ReData,
 } from "qsharp-lang/ux";
 import { HelpPage } from "./help";
+import { DocumentationView } from "./docview";
 
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore - there are no types for this
@@ -49,12 +50,18 @@ type CircuitState = {
   props: CircuitProps;
 };
 
+type DocumentationState = {
+  viewType: "documentationView";
+  contentToRender: string;
+};
+
 type State =
   | { viewType: "loading" }
   | { viewType: "help" }
   | HistogramState
   | EstimatesState
-  | CircuitState;
+  | CircuitState
+  | DocumentationState;
 const loadingState: State = { viewType: "loading" };
 const helpState: State = { viewType: "help" };
 let state: State = loadingState;
@@ -121,6 +128,14 @@ function onMessage(event: any) {
         };
       }
       break;
+    case "showDocumentationCommand":
+      {
+        state = {
+          viewType: "documentationView",
+          contentToRender: message.contentToRender,
+        };
+      }
+      break;
     default:
       console.error("Unknown command: ", message.command);
       return;
@@ -179,6 +194,13 @@ function App({ state }: { state: State }) {
       return <CircuitPanel {...state.props}></CircuitPanel>;
     case "help":
       return <HelpPage />;
+    case "documentationView":
+      return (
+        <DocumentationView
+          renderer={markdownRenderer}
+          contentToRender={state.contentToRender}
+        />
+      );
     default:
       console.error("Unknown view type in state", state);
       return <div>Loading error</div>;

vscode/src/webviewPanel.ts

@@ -23,6 +23,7 @@ import { loadProject } from "./projectSystem";
 import { EventType, sendTelemetryEvent } from "./telemetry";
 import { getRandomGuid } from "./utils";
 import { showCircuitCommand } from "./circuit";
+import { showDocumentationCommand } from "./documentation";
 
 const QSharpWebViewType = "qsharp-webview";
 const compilerRunTimeoutMs = 1000 * 60 * 5; // 5 minutes
@@ -379,9 +380,23 @@ export function registerWebViewCommands(context: ExtensionContext) {
       },
     ),
   );
+
+  context.subscriptions.push(
+    commands.registerCommand(
+      "qsharp-vscode.showDocumentation",
+      async (operation?: IOperationInfo) => {
+        await showDocumentationCommand(context.extensionUri, operation);
+      },
+    ),
+  );
 }
 
-type PanelType = "histogram" | "estimates" | "help" | "circuit";
+type PanelType =
+  | "histogram"
+  | "estimates"
+  | "help"
+  | "circuit"
+  | "documentationPanelType";
 
 const panelTypeToPanel: Record<
   PanelType,
@@ -391,6 +406,11 @@ const panelTypeToPanel: Record<
   estimates: { title: "Q# Estimates", panel: undefined, state: {} },
   circuit: { title: "Q# Circuit", panel: undefined, state: {} },
   help: { title: "Q# Help", panel: undefined, state: {} },
+  documentationPanelType: {
+    title: "Q# Documentation",
+    panel: undefined,
+    state: {},
+  },
 };
 
 export function sendMessageToPanel(
@@ -410,6 +430,7 @@ export function sendMessageToPanel(
       {
         enableCommandUris: true,
         enableScripts: true,
+        enableFindWidget: true,
         retainContextWhenHidden: true,
         // Note: If retainContextWhenHidden is false, the webview gets reloaded
         // every time you hide it by switching to another tab and then switch
@@ -528,7 +549,8 @@ export class QSharpViewViewPanelSerializer implements WebviewPanelSerializer {
       panelType !== "estimates" &&
       panelType !== "histogram" &&
       panelType !== "circuit" &&
-      panelType !== "help"
+      panelType !== "help" &&
+      panelType != "documentationPanelType"
     ) {
       // If it was loading when closed, that's fine
       if (panelType === "loading") {