introduce a DocumentationManager to the WorkspaceContext

Author: matthewbastien

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();
 
@@ -182,11 +186,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);
     }
 
     /**

src/commands.ts

@@ -39,7 +39,6 @@ import { runPluginTask } from "./commands/runPluginTask";
 import { runTestMultipleTimes } from "./commands/testMultipleTimes";
 import { newSwiftFile } from "./commands/newFile";
 import { runAllTestsParallel } from "./commands/runParallelTests";
-import { previewDocumentation } from "./commands/previewDocumentation";
 
 /**
  * References:
@@ -68,10 +67,7 @@ export function registerToolchainCommands(
 /**
  * Registers this extension's commands in the given {@link vscode.ExtensionContext context}.
  */
-export function register(
-    ctx: WorkspaceContext,
-    extension: vscode.ExtensionContext
-): vscode.Disposable[] {
+export function register(ctx: WorkspaceContext): vscode.Disposable[] {
     return [
         vscode.commands.registerCommand("swift.newFile", uri => newSwiftFile(uri)),
         vscode.commands.registerCommand("swift.resolveDependencies", () =>
@@ -146,7 +142,7 @@ export function register(
         ),
         vscode.commands.registerCommand(
             "swift.previewDocumentation",
-            async () => await previewDocumentation(extension, ctx)
+            async () => await ctx.documentation.launchDocumentationPreview()
         ),
     ];
 }

src/commands/previewDocumentation.ts

@@ -0,0 +1,92 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the VS Code Swift open source project
+//
+// Copyright (c) 2024 the VS Code Swift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of VS Code Swift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import * as vscode from "vscode";
+import * as fs from "fs/promises";
+import * as path from "path";
+import { DocumentationPreviewEditor } from "./DocumentationPreviewEditor";
+import { WorkspaceContext } from "../WorkspaceContext";
+import { FolderContext } from "../FolderContext";
+import { createSwiftTask } from "../tasks/SwiftTaskProvider";
+import { executeTaskWithUI, updateAfterError } from "../commands/utilities";
+
+export class DocumentationManager {
+    private previewEditor?: DocumentationPreviewEditor;
+
+    constructor(
+        private readonly extension: vscode.ExtensionContext,
+        private readonly context: WorkspaceContext
+    ) {}
+
+    async launchDocumentationPreview(): Promise<void> {
+        if (!this.previewEditor) {
+            const folderContext = this.context.folders.at(0);
+            if (!folderContext) {
+                return;
+            }
+
+            const archive = await this.buildDocumentation(folderContext);
+            if (!archive) {
+                return;
+            }
+
+            this.previewEditor = new DocumentationPreviewEditor(
+                archive,
+                this.extension,
+                this.context
+            );
+            const subscriptions: vscode.Disposable[] = [
+                this.previewEditor.onDidDispose(() => {
+                    subscriptions.forEach(d => d.dispose());
+                    this.previewEditor = undefined;
+                }),
+            ];
+        }
+    }
+
+    async buildDocumentation(folderContext: FolderContext): Promise<string | undefined> {
+        const buildPath = path.join(folderContext.folder.fsPath, ".build", "vscode-swift");
+        const outputPath = path.join(buildPath, "documentation-preview");
+        await fs.rm(outputPath, { recursive: true, force: true });
+        await fs.mkdir(outputPath, { recursive: true });
+        const task = createSwiftTask(
+            [
+                "package",
+                "--disable-sandbox",
+                "generate-documentation",
+                "--enable-experimental-combined-documentation",
+                "--output-path",
+                outputPath,
+            ],
+            "Build Documentation",
+            {
+                cwd: folderContext.folder,
+                env: {
+                    DOCC_HTML_DIR: this.extension.asAbsolutePath("assets/swift-docc-render"),
+                },
+                scope: folderContext.workspaceFolder,
+                prefix: folderContext.name,
+                presentationOptions: { reveal: vscode.TaskRevealKind.Silent },
+            },
+            folderContext.workspaceContext.toolchain
+        );
+        const succeeded = await executeTaskWithUI(task, "Building Documentation", folderContext);
+        updateAfterError(succeeded, folderContext);
+        if (!succeeded) {
+            vscode.window.showErrorMessage("Failed to build documentation via SwiftDocC");
+            return;
+        }
+        return outputPath;
+    }
+}