change LSP request name to convertDocumentation

matthewbastien · matthewbastien · commit be6caee347fd · 2024-12-13T09:48:35.000-05:00
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -14,7 +14,7 @@
         "VSCODE_DEBUG": "1"
       },
       "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "preLaunchTask": "build"
+      "preLaunchTask": "Build Extension"
     },
     {
       "name": "Extension Tests",
diff --git a/package.json b/package.json
@@ -24,8 +24,6 @@
   ],
   "activationEvents": [
     "onLanguage:swift",
-    "onLanguage:swift-docc-markdown",
-    "onLanguage:swift-docc-tutorial",
     "workspaceContains:Package.swift",
     "workspaceContains:compile_commands.json",
     "workspaceContains:compile_flags.txt",
@@ -63,21 +61,12 @@
         ]
       },
       {
-        "id": "swift-docc-markdown",
+        "id": "tutorial",
         "aliases": [
-          "Swift DocC Markdown"
+          "Tutorial"
         ],
         "filenamePatterns": [
-          "**/*.docc/**/*.md"
-        ]
-      },
-      {
-        "id": "swift-docc-tutorial",
-        "aliases": [
-          "Swift DocC Tutorial"
-        ],
-        "filenamePatterns": [
-          "**/*.docc/**/*.tutorial"
+          "*.tutorial"
         ]
       }
     ],
@@ -690,7 +679,7 @@
       "commandPalette": [
         {
           "command": "swift.previewDocumentation",
-          "when": "swift.supportsDocumentationRendering"
+          "when": "swift.supportsDocumentationLivePreview"
         },
         {
           "command": "swift.createNewProject",
diff --git a/src/WorkspaceContext.ts b/src/WorkspaceContext.ts
@@ -235,13 +235,13 @@ export class WorkspaceContext implements vscode.Disposable {
             const experimentalCaps = client.initializeResult?.capabilities.experimental;
             if (!experimentalCaps) {
                 contextKeys.supportsReindexing = false;
-                contextKeys.supportsDocumentationRendering = false;
+                contextKeys.supportsDocumentationLivePreview = false;
                 return;
             }
             contextKeys.supportsReindexing =
                 experimentalCaps["workspace/triggerReindex"] !== undefined;
-            contextKeys.supportsDocumentationRendering =
-                experimentalCaps["textDocument/renderDocumentation"] !== undefined;
+            contextKeys.supportsDocumentationLivePreview =
+                experimentalCaps["textDocument/convertDocumentation"] !== undefined;
         });
 
         setSnippetContextKey(this);
diff --git a/src/contextKeys.ts b/src/contextKeys.ts
@@ -69,9 +69,9 @@ interface ContextKeys {
     supportsReindexing: boolean;
 
     /**
-     * Whether the SourceKit-LSP server supports documentation rendering.
+     * Whether the SourceKit-LSP server supports documentation live preview.
      */
-    supportsDocumentationRendering: boolean;
+    supportsDocumentationLivePreview: boolean;
 }
 
 /** Creates the getters and setters for the VS Code Swift extension's context keys. */
@@ -85,7 +85,7 @@ function createContextKeys(): ContextKeys {
     let lldbVSCodeAvailable: boolean = false;
     let createNewProjectAvailable: boolean = false;
     let supportsReindexing: boolean = false;
-    let supportsDocumentationRendering: boolean = false;
+    let supportsDocumentationLivePreview: boolean = false;
 
     return {
         get isActivated() {
@@ -173,15 +173,15 @@ function createContextKeys(): ContextKeys {
             vscode.commands.executeCommand("setContext", "swift.supportsReindexing", value);
         },
 
-        get supportsDocumentationRendering() {
-            return supportsDocumentationRendering;
+        get supportsDocumentationLivePreview() {
+            return supportsDocumentationLivePreview;
         },
 
-        set supportsDocumentationRendering(value: boolean) {
-            supportsDocumentationRendering = value;
+        set supportsDocumentationLivePreview(value: boolean) {
+            supportsDocumentationLivePreview = value;
             vscode.commands.executeCommand(
                 "setContext",
-                "swift.supportsDocumentationRendering",
+                "swift.supportsDocumentationLivePreview",
                 value
             );
         },
diff --git a/src/documentation/DocumentationManager.ts b/src/documentation/DocumentationManager.ts
@@ -15,12 +15,12 @@
 import * as vscode from "vscode";
 import { DocumentationPreviewEditor } from "./DocumentationPreviewEditor";
 import { WorkspaceContext } from "../WorkspaceContext";
-import { RenderNode } from "./webview/WebviewMessage";
+import { WebviewContent } from "./webview/WebviewMessage";
 import contextKeys from "../contextKeys";
 
 export class DocumentationManager implements vscode.Disposable {
     private previewEditor?: DocumentationPreviewEditor;
-    private editorUpdatedContentEmitter = new vscode.EventEmitter<RenderNode>();
+    private editorUpdatedContentEmitter = new vscode.EventEmitter<WebviewContent>();
     private editorRenderedEmitter = new vscode.EventEmitter<void>();
 
     constructor(
@@ -32,7 +32,7 @@ export class DocumentationManager implements vscode.Disposable {
     onPreviewDidRenderContent = this.editorRenderedEmitter.event;
 
     async launchDocumentationPreview(): Promise<boolean> {
-        if (!contextKeys.supportsDocumentationRendering) {
+        if (!contextKeys.supportsDocumentationLivePreview) {
             return false;
         }
 
diff --git a/src/documentation/DocumentationPreviewEditor.ts b/src/documentation/DocumentationPreviewEditor.ts
@@ -15,9 +15,9 @@
 import * as vscode from "vscode";
 import * as fs from "fs/promises";
 import * as path from "path";
-import { RenderNode, WebviewMessage } from "./webview/WebviewMessage";
+import { RenderNode, WebviewContent, WebviewMessage } from "./webview/WebviewMessage";
 import { WorkspaceContext } from "../WorkspaceContext";
-import { RenderDocumentationRequest } from "../sourcekit-lsp/extensions/RenderDocumentationRequest";
+import { ConvertDocumentationRequest } from "../sourcekit-lsp/extensions/ConvertDocumentationRequest";
 
 export enum PreviewEditorConstant {
     VIEW_TYPE = "swift.previewDocumentationEditor",
@@ -30,7 +30,7 @@ export class DocumentationPreviewEditor implements vscode.Disposable {
 
     private disposeEmitter = new vscode.EventEmitter<void>();
     private renderEmitter = new vscode.EventEmitter<void>();
-    private updateContentEmitter = new vscode.EventEmitter<RenderNode>();
+    private updateContentEmitter = new vscode.EventEmitter<WebviewContent>();
 
     constructor(
         private readonly extension: vscode.ExtensionContext,
@@ -66,10 +66,10 @@ export class DocumentationPreviewEditor implements vscode.Disposable {
                 this.subscriptions.push(
                     this.webviewPanel.webview.onDidReceiveMessage(this.receiveMessage.bind(this)),
                     vscode.window.onDidChangeActiveTextEditor(editor => {
-                        this.renderDocumentation(editor);
+                        this.convertDocumentation(editor);
                     }),
                     vscode.window.onDidChangeTextEditorSelection(event => {
-                        this.renderDocumentation(event.textEditor);
+                        this.convertDocumentation(event.textEditor);
                     }),
                     this.webviewPanel.onDidDispose(this.dispose.bind(this))
                 );
@@ -109,36 +109,46 @@ export class DocumentationPreviewEditor implements vscode.Disposable {
     private receiveMessage(message: WebviewMessage) {
         switch (message.type) {
             case "loaded":
-                this.renderDocumentation(vscode.window.activeTextEditor);
+                this.convertDocumentation(vscode.window.activeTextEditor);
                 break;
             case "rendered":
                 this.renderEmitter.fire();
                 break;
         }
     }
 
-    private async renderDocumentation(editor: vscode.TextEditor | undefined): Promise<void> {
+    private async convertDocumentation(editor: vscode.TextEditor | undefined): Promise<void> {
         const document = editor?.document;
         if (!document || document.uri.scheme !== "file") {
             return undefined;
         }
 
         const response = await this.context.languageClientManager.useLanguageClient(
             async client => {
-                return await client.sendRequest(RenderDocumentationRequest.type, {
+                return await client.sendRequest(ConvertDocumentationRequest.type, {
                     textDocument: {
                         uri: document.uri.toString(),
                     },
                     position: editor.selection.start,
                 });
             }
         );
-        if (!response.content) {
+        if (response.type === "error") {
+            this.postMessage({
+                type: "update-content",
+                content: {
+                    type: "error",
+                    errorMessage: response.error.message,
+                },
+            });
             return;
         }
         this.postMessage({
             type: "update-content",
-            content: this.parseRenderNode(response.content),
+            content: {
+                type: "render-node",
+                renderNode: this.parseRenderNode(response.renderNode),
+            },
         });
     }
 
diff --git a/src/documentation/webview/WebviewMessage.ts b/src/documentation/webview/WebviewMessage.ts
@@ -37,13 +37,34 @@ export interface RenderedMessage {
  * Sent from the extension to the webview to update its contents. The data
  * format is the same as DocC's JSON index.
  *
+ * Automatically removes any other loading/error messages.
+ *
  * This must be sent AFTER the webview has done at least one render.
  */
 export interface UpdateContentMessage {
     type: "update-content";
-    content: RenderNode;
+    content: WebviewContent;
 }
 
+export type WebviewContent = RenderNodeContent | ErrorContent;
+
+export interface RenderNodeContent {
+    type: "render-node";
+    renderNode: RenderNode;
+}
+
+export interface ErrorContent {
+    type: "error";
+    errorMessage: string;
+}
+
+/**
+ * A Swift DocC render node that represents a single page of documentation.
+ *
+ * In order to maintain maximum compatibility this interface only exposes the bare minimum
+ * that we need to support live preview. This interface must be kept up to date with
+ * https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/Model/Rendering/RenderNode.swift
+ */
 export interface RenderNode {
     schemaVersion: {
         major: number;
diff --git a/src/documentation/webview/webview.ts b/src/documentation/webview/webview.ts
@@ -12,14 +12,16 @@
 //
 //===----------------------------------------------------------------------===//
 
-import { RenderNode, WebviewMessage } from "./WebviewMessage";
+import { RenderNode, WebviewContent, WebviewMessage } from "./WebviewMessage";
 import { createCommunicationBridge } from "./CommunicationBridge";
 
 createCommunicationBridge().then(async bridge => {
     const vscode = acquireVsCodeApi();
     let activeDocumentationPath: string | undefined;
     let contentToApplyOnRender: RenderNode | undefined;
 
+    window.document.getElementById("app");
+
     // Handle messages coming from swift-docc-render
     bridge.onDidReceiveMessage(message => {
         switch (message.type) {
@@ -49,27 +51,32 @@ createCommunicationBridge().then(async bridge => {
                 break;
         }
     });
-    function handleUpdateContentMessage(renderNode: RenderNode) {
-        const documentationPath: string = (() => {
-            switch (renderNode.kind) {
-                case "symbol":
-                case "article":
-                    return "/live/documentation";
-                case "overview":
-                    return "/live/tutorials-overview";
-                default:
-                    return "/live/tutorials";
+    function handleUpdateContentMessage(content: WebviewContent) {
+        if (content.type === "render-node") {
+            const renderNode = content.renderNode;
+            const documentationPath: string = (() => {
+                switch (renderNode.kind) {
+                    case "symbol":
+                    case "article":
+                        return "/live/documentation";
+                    case "overview":
+                        return "/live/tutorials-overview";
+                    default:
+                        return "/live/tutorials";
+                }
+            })();
+            if (activeDocumentationPath !== documentationPath) {
+                activeDocumentationPath = documentationPath;
+                contentToApplyOnRender = renderNode;
+                bridge.send({
+                    type: "navigation",
+                    data: documentationPath,
+                });
+            } else {
+                bridge.send({ type: "contentUpdate", data: renderNode });
             }
-        })();
-        if (activeDocumentationPath !== documentationPath) {
-            activeDocumentationPath = documentationPath;
-            contentToApplyOnRender = renderNode;
-            bridge.send({
-                type: "navigation",
-                data: documentationPath,
-            });
         } else {
-            bridge.send({ type: "contentUpdate", data: renderNode });
+            // Show the error message
         }
     }
 
diff --git a/src/sourcekit-lsp/LanguageClientManager.ts b/src/sourcekit-lsp/LanguageClientManager.ts
@@ -75,10 +75,10 @@ export class LanguageClientManager implements vscode.Disposable {
     ];
     // document selector for swift-docc documentation
     static documentationDocumentSelector: SourceKitDocumentSelector = [
-        { scheme: "file", language: "swift-docc-markdown" },
-        { scheme: "untitled", language: "swift-docc-markdown" },
-        { scheme: "file", language: "swift-docc-tutorial" },
-        { scheme: "untitiled", language: "swift-docc-tutorial" },
+        { scheme: "file", language: "markdown" },
+        { scheme: "untitled", language: "markdown" },
+        { scheme: "file", language: "tutorial" },
+        { scheme: "untitiled", language: "tutorial" },
     ];
     static get documentSelector(): DocumentSelector {
         let documentSelector: SourceKitDocumentSelector;
diff --git a/src/sourcekit-lsp/extensions/ConvertDocumentationRequest.ts b/src/sourcekit-lsp/extensions/ConvertDocumentationRequest.ts
diff --git a/src/sourcekit-lsp/extensions/RenderDocumentationRequest.ts b/src/sourcekit-lsp/extensions/RenderDocumentationRequest.ts
diff --git a/test/integration-tests/documentation/DocumentationPreview.test.ts b/test/integration-tests/documentation/DocumentationPreview.test.ts

Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,7 @@`
`14`	`14`	`"VSCODE_DEBUG": "1"`
`15`	`15`	`},`
`16`	`16`	`"outFiles": ["${workspaceFolder}/dist/*/.js"],`
`17`		`- "preLaunchTask": "build"`
	`17`	`+ "preLaunchTask": "Build Extension"`
`18`	`18`	`},`
`19`	`19`	`{`
`20`	`20`	`"name": "Extension Tests",`