Documentation Preview Editor (#1181)

Author: matthewbastien

.eslintrc.json

@@ -26,5 +26,5 @@
     ]
   },
   "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended", "prettier"],
-  "ignorePatterns": ["out", "dist", "**/*.d.ts"]
+  "ignorePatterns": ["assets", "out", "dist", "**/*.d.ts"]
 }

.gitignore

@@ -7,5 +7,7 @@ default.profraw
 *.vsix
 .vscode-test
 .build
+.DS_Store
+assets/documentation-webview
 assets/test/**/Package.resolved
-assets/swift-docc-render
+assets/swift-docc-render

.vscode/launch.json

@@ -14,7 +14,7 @@
         "VSCODE_DEBUG": "1"
       },
       "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "preLaunchTask": "build"
+      "preLaunchTask": "Build Extension"
     },
     {
       "name": "Extension Tests",

.vscode/settings.json

@@ -8,6 +8,8 @@
   },
   // Turn off tsc task auto detection since we have the necessary tasks as npm scripts
   "typescript.tsc.autoDetect": "off",
+  // Tell VS Code to use the same version of TypeScript as the build
+  "typescript.tsdk": "node_modules/typescript/lib",
 
   // Configure Prettier
   "editor.formatOnSave": true,

.vscode/tasks.json

@@ -4,7 +4,15 @@
   "version": "2.0.0",
   "tasks": [
     {
-      "label": "build",
+      "label": "Build Extension",
+      "dependsOn": ["compile", "compile-documentation-webview"],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    },
+    {
+      "label": "compile",
       "type": "npm",
       "script": "watch",
       "problemMatcher": "$tsc-watch",
@@ -13,8 +21,49 @@
       },
       "isBackground": true,
       "group": {
-        "kind": "build",
-        "isDefault": true
+        "kind": "build"
+      }
+    },
+    {
+      "label": "compile-documentation-webview",
+      "type": "npm",
+      "script": "watch-documentation-webview",
+      "problemMatcher": [
+        {
+          "owner": "esbuild",
+          "severity": "error",
+          "source": "esbuild",
+          "fileLocation": "relative",
+          "background": {
+            "activeOnStart": true,
+            "beginsPattern": {
+              "regexp": "\\[watch\\] build started"
+            },
+            "endsPattern": {
+              "regexp": "\\[watch\\] build finished"
+            }
+          },
+          "pattern": [
+            {
+              "regexp": "^[✘▲] \\[([A-Z]+)\\] (.+)",
+              "severity": 1,
+              "message": 2
+            },
+            {
+              "regexp": "^(?:\\t| {4})(?!\\s)([^:]+)(?::([0-9]+))?(?::([0-9]+))?:$",
+              "file": 1,
+              "line": 2,
+              "column": 3
+            }
+          ]
+        }
+      ],
+      "presentation": {
+        "reveal": "never"
+      },
+      "isBackground": true,
+      "group": {
+        "kind": "build"
       }
     },
     {

package.json

@@ -59,6 +59,15 @@
           ".swiftinterface",
           ".swift"
         ]
+      },
+      {
+        "id": "tutorial",
+        "aliases": [
+          "Tutorial"
+        ],
+        "filenamePatterns": [
+          "*.tutorial"
+        ]
       }
     ],
     "snippets": [
@@ -76,6 +85,11 @@
       }
     ],
     "commands": [
+      {
+        "command": "swift.previewDocumentation",
+        "title": "Preview Documentation",
+        "category": "Swift"
+      },
       {
         "command": "swift.createNewProject",
         "title": "Create New Project...",
@@ -663,6 +677,10 @@
         }
       ],
       "commandPalette": [
+        {
+          "command": "swift.previewDocumentation",
+          "when": "swift.supportsDocumentationLivePreview"
+        },
         {
           "command": "swift.createNewProject",
           "when": "!swift.isActivated || swift.createNewProjectAvailable"
@@ -1274,9 +1292,13 @@
   ],
   "scripts": {
     "vscode:prepublish": "npm run bundle",
-    "bundle": "del-cli ./dist && esbuild ./src/extension.ts --bundle --outfile=dist/src/extension.js --external:vscode --format=cjs --platform=node --target=node18 --minify --sourcemap",
-    "compile": "del-cli ./dist && tsc",
-    "watch": "del-cli ./dist && tsc --watch",
+    "bundle": "del-cli ./dist && npm run bundle-extension && npm run bundle-documentation-webview",
+    "bundle-extension": "del-cli ./dist && esbuild ./src/extension.ts --bundle --outfile=dist/src/extension.js --external:vscode --format=cjs --platform=node --target=node18 --minify --sourcemap",
+    "bundle-documentation-webview": "npm run compile-documentation-webview -- --minify",
+    "compile": "del-cli ./dist/ && tsc --build",
+    "watch": "npm run compile -- --watch",
+    "compile-documentation-webview": "del-cli ./assets/documentation-webview && esbuild ./src/documentation/webview/webview.ts --bundle --outfile=assets/documentation-webview/index.js --format=cjs --sourcemap",
+    "watch-documentation-webview": "npm run compile-documentation-webview -- --watch",
     "lint": "eslint ./ --ext ts && tsc --noEmit",
     "update-swift-docc-render": "tsx ./scripts/update_swift_docc_render.ts",
     "format": "prettier --check .",

src/WorkspaceContext.ts

@@ -33,6 +33,7 @@ import { DebugAdapter, LaunchConfigType } from "./debugger/debugAdapter";
 import { SwiftBuildStatus } from "./ui/SwiftBuildStatus";
 import { SwiftToolchain } from "./toolchain/toolchain";
 import { DiagnosticsManager } from "./DiagnosticsManager";
+import { DocumentationManager } from "./documentation/DocumentationManager";
 
 /**
  * Context for whole workspace. Holds array of contexts for each workspace folder
@@ -49,10 +50,12 @@ export class WorkspaceContext implements vscode.Disposable {
     public diagnostics: DiagnosticsManager;
     public subscriptions: vscode.Disposable[];
     public commentCompletionProvider: CommentCompletionProviders;
+    public documentation: DocumentationManager;
     private lastFocusUri: vscode.Uri | undefined;
     private initialisationFinished = false;
 
     private constructor(
+        extensionContext: vscode.ExtensionContext,
         public tempFolder: TemporaryFolder,
         public outputChannel: SwiftOutputChannel,
         public toolchain: SwiftToolchain
@@ -62,6 +65,7 @@ export class WorkspaceContext implements vscode.Disposable {
         this.languageClientManager = new LanguageClientManager(this);
         this.tasks = new TaskManager(this);
         this.diagnostics = new DiagnosticsManager(this);
+        this.documentation = new DocumentationManager(extensionContext, this);
         this.currentDocument = null;
         this.commentCompletionProvider = new CommentCompletionProviders();
 
@@ -163,6 +167,7 @@ export class WorkspaceContext implements vscode.Disposable {
             onChangeConfig,
             this.tasks,
             this.diagnostics,
+            this.documentation,
             this.languageClientManager,
             this.outputChannel,
             this.statusItem,
@@ -192,11 +197,12 @@ export class WorkspaceContext implements vscode.Disposable {
 
     /** Get swift version and create WorkspaceContext */
     static async create(
+        extensionContext: vscode.ExtensionContext,
         outputChannel: SwiftOutputChannel,
         toolchain: SwiftToolchain
     ): Promise<WorkspaceContext> {
         const tempFolder = await TemporaryFolder.create();
-        return new WorkspaceContext(tempFolder, outputChannel, toolchain);
+        return new WorkspaceContext(extensionContext, tempFolder, outputChannel, toolchain);
     }
 
     /**
@@ -224,11 +230,18 @@ export class WorkspaceContext implements vscode.Disposable {
             contextKeys.currentTargetType = undefined;
         }
 
-        // LSP can be configured per workspace to support reindexing
+        // Set context keys that depend on features from SourceKit-LSP
         this.languageClientManager.useLanguageClient(async client => {
             const experimentalCaps = client.initializeResult?.capabilities.experimental;
+            if (!experimentalCaps) {
+                contextKeys.supportsReindexing = false;
+                contextKeys.supportsDocumentationLivePreview = false;
+                return;
+            }
             contextKeys.supportsReindexing =
-                experimentalCaps && experimentalCaps["workspace/triggerReindex"] !== undefined;
+                experimentalCaps["workspace/triggerReindex"] !== undefined;
+            contextKeys.supportsDocumentationLivePreview =
+                experimentalCaps["textDocument/convertDocumentation"] !== undefined;
         });
 
         setSnippetContextKey(this);

src/commands.ts

@@ -75,6 +75,7 @@ export enum Commands {
     USE_LOCAL_DEPENDENCY = "swift.useLocalDependency",
     UNEDIT_DEPENDENCY = "swift.uneditDependency",
     RUN_PLUGIN_TASK = "swift.runPluginTask",
+    PREVIEW_DOCUMENTATION = "swift.previewDocumentation",
 }
 
 /**
@@ -155,5 +156,9 @@ export function register(ctx: WorkspaceContext): vscode.Disposable[] {
             "swift.runAllTestsParallel",
             async () => await runAllTestsParallel(ctx)
         ),
+        vscode.commands.registerCommand(
+            Commands.PREVIEW_DOCUMENTATION,
+            async () => await ctx.documentation.launchDocumentationPreview()
+        ),
     ];
 }