Convert docs to DocC

.gitignore

@@ -13,3 +13,4 @@ assets/documentation-webview
 assets/test/**/Package.resolved
 assets/swift-docc-render
 ud
+userdocs/userdocs.docc/.docc-build

README.md

@@ -10,116 +10,13 @@ This extension adds language support for Swift to Visual Studio Code, providing
 * Package dependency view
 * Test Explorer view
 
-This extension uses [SourceKit LSP](https://github.com/apple/sourcekit-lsp) for the [language server](https://microsoft.github.io/language-server-protocol/overviews/lsp/overview/), which powers code completion. It also has a dependency on [LLDB DAP](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap) for debugging.
-
-To propose new features, you can post on the [swift.org forums](https://forums.swift.org) in the [VS Code Swift Extension category](https://forums.swift.org/c/related-projects/vscode-swift-extension/). If you run into something that doesn't work the way you'd expect, you can [file an issue in the GitHub repository](https://github.com/swiftlang/vscode-swift/issues/new).
-
-## Installation
-
-The Swift extension is supported on macOS, Linux, and Windows. To install, firstly ensure you have [Swift installed on your system](https://www.swift.org/install/). Then [install the Swift extension](https://marketplace.visualstudio.com/items?itemName=swiftlang.swift-vscode). Once your machine is ready, you can get started with the **Swift: Create New Project...** command.
-
-## Features
-
-### Language features
-
-The extension provides language features such as code completion and jump to definition via [SourceKit-LSP](https://github.com/apple/sourcekit-lsp). To ensure the extension functions correctly, it’s important to first build the project so that SourceKit-LSP has access to all the symbol data. Whenever you add a new dependency to your project, make sure to rebuild it so that SourceKit-LSP can update its information.
-
-### Automatic task creation
-
-For workspaces that contain a **Package.swift** file, this extension will add the following tasks:
-
-- **Build All**: Build all targets in the Package
-- **Build Debug <Executable>**: Each executable in a Package.swift get a task for building a debug build
-- **Build Release <Executable>**: Each executable in a Package.swift get a task for building a release build
-
-These tasks are available via **Terminal ▸ Run Task...** and **Terminal ▸ Run Build Task...**.
-
-### Commands
-
-The extension adds the following commands, available via the command palette.
-
-#### Configuration
-
-- **Create New Project...**: Create a new Swift project using a template. This opens a dialog to guide you through creating a new project structure.
-- **Create New Swift File...**: Create a new `.swift` file in the current workspace.
-- **Select Toolchain**: Select the locally installed Swift toolchain (including Xcode toolchains on macOS) that you want to use Swift tools from.
-
-The following command is only available on macOS:
-
-- **Select Target Platform**: This is an experimental command that offers code editing support for iOS, tvOS, watchOS and visionOS projects.
-
-#### Building and Debugging
-
-- **Run Build**: Run `swift build` for the package associated with the open file.
-- **Debug Build**: Run `swift build` with debugging enabled for the package associated with the open file, launching the binary and attaching the debugger.
-- **Attach to Process...**: Attach the debugger to an already running process for debugging.
-- **Clean Build Folder**: Clean the build folder for the package associated with the open file, removing all previously built products.
-
-#### Dependency Management
+# Documentation
 
-- **Resolve Package Dependencies**: Run `swift package resolve` on packages associated with the open file.
-- **Update Package Dependencies**: Run `swift package update` on packages associated with the open file.
-- **Reset Package Dependencies**: Run `swift package reset` on packages associated with the open file.
-- **Add to Workspace**: Add the current package to the active workspace in VS Code.
-- **Clean Build**: Run `swift package clean` on packages associated with the open file.
-- **Open Package.swift**: Open `Package.swift` for the package associated with the open file.
-- **Use Local Version**: Switch the package dependency to use a local version of the package instead of the remote repository version.
-- **Edit Locally**: Make the package dependency editable locally, allowing changes to the dependency to be reflected immediately.
-- **Revert To Original Version**: Revert the package dependency to its original, unedited state after local changes have been made.
-- **View Repository**: Open the external repository of the selected Swift package in a browser.
+The official documentation for this extension is available at [vscode-swift](https://www.swift.org/vscode/documentation/vscode)
 
-#### Testing
-
-- **Test: Run All Tests**: Run all the tests across all test targes in the open project.
-- **Test: Rerun Last Run**: Perform the last test run again.
-- **Test: Open Coverage**: Open the last generated coverage report, if one exists.
-- **Test: Run All Tests in Parallel**: Run all tests in parallel. This action only affects XCTests. Swift-testing tests are parallel by default, and their parallelism [is controlled in code](https://developer.apple.com/documentation/testing/parallelization).
-
-#### Snippets and Scripts
-
-- **Insert Function Comment**: Insert a standard comment block for documenting a Swift function in the current file.
-- **Run Swift Script**: Run the currently open file, as a Swift script. The file must not be part of a build target. If the file has not been saved it will save it to a temporary file so it can be run.
-- **Run Swift Snippet**: If the currently open file is a Swift snippet then run it.
-- **Debug Swift Snippet**: If the currently open file is a Swift snippet then debug it.
-
-#### Diagnostics
-
-- **Capture VS Code Swift Diagnostic Bundle**: Capture a diagnostic bundle from VS Code, containing logs and information to aid in troubleshooting Swift-related issues.
-- **Clear Diagnostics Collection**: Clear all collected diagnostics in the current workspace to start fresh.
-- **Restart LSP Server**: Restart the Swift Language Server Protocol (LSP) server for the current workspace.
-- **Re-Index Project**: Force a re-index of the project to refresh code completion and symbol navigation support.
-
-### Package dependencies
-
-If your workspace contains a package that has dependencies, this extension will add a **Package Dependencies** view to the Explorer:
-
-![](images/package-dependencies.png)
-
-Additionally, the extension will monitor `Package.swift` and `Package.resolved` for changes, resolve any changes to the dependencies, and update the view as needed.
-
-### Debugging
-
-The Swift extension uses the [LLDB DAP](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap) extension for debugging.
-
-When you open a Swift package (a directory containing a `Package.swift` file), the extension automatically generates build tasks and launch configurations for each executable within the package. Additionally, if the package includes tests, the extension creates a configuration specifically designed to run those tests. These configurations all leverage the CodeLLDB extension as the debugger of choice.
-
-Use the **Run > Start Debugging** menu item to run an executable and start debugging. If you have multiple launch configurations you can choose which launch configuration to use in the debugger view.
-
-CodeLLDB includes a version of `lldb` that it uses by default for debugging, but this version of `lldb` doesn’t support Swift. The Swift extension will automatically identify the required version and offer to update the CodeLLDB configuration as necessary so that debugging is supported.
-
-### Test Explorer
-
-If your package contains tests then they can be viewed, run and debugged in the Test Explorer.
-
-![](images/test-explorer.png)
-
-Once your project is built, the Test Explorer will list all your tests. These tests are grouped by package, then test target, and finally, by XCTestCase class. From the Test Explorer, you can initiate a test run, debug a test run, and if a file has already been opened, you can jump to the source code for a test.
-
-### Documentation
+This extension uses [SourceKit LSP](https://github.com/apple/sourcekit-lsp) for the [language server](https://microsoft.github.io/language-server-protocol/overviews/lsp/overview/), which powers code completion. It also has a dependency on [LLDB DAP](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap) for debugging.
 
-* [Extension Settings](docs/settings.md)
-* [Test Coverage](docs/test-coverage.md)
-* [Visual Studio Code Dev Containers](docs/remote-dev.md)
+To propose new features, you can post on the [swift.org forums](https://forums.swift.org) in the [VS Code Swift Extension category](https://forums.swift.org/c/related-projects/vscode-swift-extension/). If you run into something that doesn't work the way you'd expect, you can [file an issue in the GitHub repository](https://github.com/swiftlang/vscode-swift/issues/new).
 
 ## Contributing
 

package.json

@@ -299,6 +299,12 @@
         "title": "Run Tests with Coverage",
         "category": "Test",
         "icon": "$(debug-coverage)"
+      },
+      {
+        "command": "swift.openDocumentation",
+        "title": "Open Documentation",
+        "category": "Swift",
+        "icon": "$(book)"
       }
     ],
     "configuration": [
@@ -1068,6 +1074,11 @@
           "command": "swift.nestedDependenciesList",
           "when": "view == projectPanel && swift.flatDependenciesList",
           "group": "navigation@5"
+        },
+        {
+          "command": "swift.openDocumentation",
+          "when": "view == projectPanel",
+          "group": "navigation@6"
         }
       ],
       "view/item/context": [

src/commands.ts

@@ -44,6 +44,7 @@ import { updateDependenciesViewList } from "./commands/dependencies/updateDepVie
 import { runTask } from "./commands/runTask";
 import { TestKind } from "./TestExplorer/TestKind";
 import { pickProcess } from "./commands/pickProcess";
+import { openDocumentation } from "./commands/openDocumentation";
 
 /**
  * References:
@@ -209,6 +210,7 @@ export function register(ctx: WorkspaceContext): vscode.Disposable[] {
         vscode.commands.registerCommand("swift.openEducationalNote", uri =>
             openEducationalNote(uri)
         ),
+        vscode.commands.registerCommand("swift.openDocumentation", () => openDocumentation()),
     ];
 }
 

src/commands/openDocumentation.ts

@@ -0,0 +1,24 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the VS Code Swift open source project
+//
+// Copyright (c) 2025 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";
+
+/**
+ * Handle the user requesting to show the vscode-swift documentation.
+ */
+export async function openDocumentation(): Promise<void> {
+    await vscode.env.openExternal(
+        vscode.Uri.parse("https://www.swift.org/vscode/documentation/vscode")
+    );
+}

userdocs/userdocs.docc/automatic-task-creation.md

@@ -0,0 +1,13 @@
+# Automatic Task Creation
+
+vscode-swift automatically adds tasks for common operations with your Package.
+
+> Tip: Tasks use workflows common to all VSCode extensions. For more information see https://code.visualstudio.com/docs/editor/tasks
+
+For workspaces that contain a **Package.swift** file, this extension will add the following tasks:
+
+- **Build All**: Build all targets in the Package
+- **Build Debug <Executable>**: Each executable in a Package.swift get a task for building a debug build
+- **Build Release <Executable>**: Each executable in a Package.swift get a task for building a release build
+
+These tasks are available via **Terminal ▸ Run Task...** and **Terminal ▸ Run Build Task...**.

userdocs/userdocs.docc/commands.md

@@ -0,0 +1,56 @@
+# Commands
+
+vscode-swift adds various commands to Visual Studio Code.
+
+The extension adds the following commands, available via the command palette.
+
+#### Configuration
+
+- **Create New Project...**: Create a new Swift project using a template. This opens a dialog to guide you through creating a new project structure.
+- **Create New Swift File...**: Create a new `.swift` file in the current workspace.
+- **Select Toolchain**: Select the locally installed Swift toolchain (including Xcode toolchains on macOS) that you want to use Swift tools from.
+
+The following command is only available on macOS:
+
+- **Select Target Platform**: This is an experimental command that offers code completion for iOS and tvOS projects.
+
+#### Building and Debugging
+
+- **Run Build**: Run `swift build` for the package associated with the open file.
+- **Debug Build**: Run `swift build` with debugging enabled for the package associated with the open file, launching the binary and attaching the debugger.
+- **Attach to Process...**: Attach the debugger to an already running process for debugging.
+- **Clean Build Folder**: Clean the build folder for the package associated with the open file, removing all previously built products.
+
+#### Dependency Management
+
+- **Resolve Package Dependencies**: Run `swift package resolve` on packages associated with the open file.
+- **Update Package Dependencies**: Run `swift package update` on packages associated with the open file.
+- **Reset Package Dependencies**: Run `swift package reset` on packages associated with the open file.
+- **Add to Workspace**: Add the current package to the active workspace in VS Code.
+- **Clean Build**: Run `swift package clean` on packages associated with the open file.
+- **Open Package.swift**: Open `Package.swift` for the package associated with the open file.
+- **Use Local Version**: Switch the package dependency to use a local version of the package instead of the remote repository version.
+- **Edit Locally**: Make the package dependency editable locally, allowing changes to the dependency to be reflected immediately.
+- **Revert To Original Version**: Revert the package dependency to its original, unedited state after local changes have been made.
+- **View Repository**: Open the external repository of the selected Swift package in a browser.
+
+#### Testing
+
+- **Test: Run All Tests**: Run all the tests across all test targes in the open project.
+- **Test: Rerun Last Run**: Perform the last test run again.
+- **Test: Open Coverage**: Open the last generated coverage report, if one exists.
+- **Test: Run All Tests in Parallel**: Run all tests in parallel. This action only affects XCTests. Swift-testing tests are parallel by default, and their parallelism [is controlled in code](https://developer.apple.com/documentation/testing/parallelization).
+
+#### Snippets and Scripts
+
+- **Insert Function Comment**: Insert a standard comment block for documenting a Swift function in the current file.
+- **Run Swift Script**: Run the currently open file, as a Swift script. The file must not be part of a build target. If the file has not been saved it will save it to a temporary file so it can be run.
+- **Run Swift Snippet**: If the currently open file is a Swift snippet then run it.
+- **Debug Swift Snippet**: If the currently open file is a Swift snippet then debug it.
+
+#### Diagnostics
+
+- **Capture VS Code Swift Diagnostic Bundle**: Capture a diagnostic bundle from VS Code, containing logs and information to aid in troubleshooting Swift-related issues.
+- **Clear Diagnostics Collection**: Clear all collected diagnostics in the current workspace to start fresh.
+- **Restart LSP Server**: Restart the Swift Language Server Protocol (LSP) server for the current workspace.
+- **Re-Index Project**: Force a re-index of the project to refresh code completion and symbol navigation support.

userdocs/userdocs.docc/debugging.md

@@ -0,0 +1,11 @@
+# Debugging
+
+vscode-swift allows you to debug your Swift packages.
+
+> Tip: Debugging works best when using a version of the Swift toolchain 6.0 or higher
+
+> Tip: Debugging uses workflows common to all VSCode extensions. For more information see https://code.visualstudio.com/docs/editor/debugging
+
+When you open a Swift package (a directory containing a `Package.swift` file), the extension automatically generates build tasks and launch configurations for each executable within the package. Additionally, if the package includes tests, the extension creates a configuration specifically designed to run those tests. These configurations all leverage the CodeLLDB extension as the debugger of choice.
+
+Use the **Run > Start Debugging** menu item to run an executable and start debugging. If you have multiple launch configurations you can choose which launch configuration to use in the debugger view.

userdocs/userdocs.docc/docc-previews.md

@@ -0,0 +1,7 @@
+# DocC Preview
+
+vscode-swift supports rendering your DocC documentation
+
+> Warning: DocC Preview is only supported with Swift toolchains versioned 6.2 or higher
+
+Docs here!

userdocs/userdocs.docc/installation.md

@@ -0,0 +1,7 @@
+# Installation
+
+vscode-code Swift is installed through the extension marketplace.
+
+The Swift extension is supported on macOS, Linux, and Windows.
+
+To install, firstly ensure you have [Swift installed on your system](https://www.swift.org/install/). Then [install the Swift extension](https://marketplace.visualstudio.com/items?itemName=swiftlang.swift-vscode). Once your machine is ready, you can get started with the **Swift: Create New Project...** command.

userdocs/userdocs.docc/language-features.md

@@ -0,0 +1,5 @@
+# Language Features
+
+vscode-swift provides various language features to help you write Swift code.
+
+The extension provides language features such as code completion and jump to definition via [SourceKit-LSP](https://github.com/apple/sourcekit-lsp). To ensure the extension functions correctly, it’s important to first build the project so that SourceKit-LSP has access to all the symbol data. Whenever you add a new dependency to your project, make sure to rebuild it so that SourceKit-LSP can update its information.

userdocs/userdocs.docc/project-view.md

@@ -0,0 +1,9 @@
+# Project View
+
+vscode-swift provides project view
+
+If your workspace contains a package, this extension will add a **Swift Project** view to the Explorer:
+
+![](images/package-dependencies.png)
+
+Additionally, the extension will monitor `Package.swift` and `Package.resolved` for changes, resolve any changes to the dependencies, and update the view as needed.

docs/remote-dev.md → userdocs/userdocs.docc/remote-dev.md

@@ -1,5 +1,7 @@
 # Visual Studio Code Dev Containers
 
+Dev containers can be used as an easy way to develop when building for other platforms.
+
 [VS Code Dev Containers](https://code.visualstudio.com/docs/remote/containers) allows you to run your code and environment in a container. This is especially useful for Swift when developing on macOS and deploying to Linux. You can ensure there are no compatibility issues in Foundation when running your code. The extension also works with [GitHub Codespaces](https://github.com/features/codespaces) to allow you to write your code on the web.
 
 ## Requirements

docs/settings.md → userdocs/userdocs.docc/settings.md

@@ -1,5 +1,7 @@
 # Extension Settings
 
+vscode-swift provides various settings to configure its behaviour.
+
 The Visual Studio Code Swift extension comes with a number of settings you can use to control how it works. Detailed descriptions of each setting is provided in the extension settings page.
 
 This document outlines useful configuration options not covered by the settings descriptions in the extension settings page.

userdocs/userdocs.docc/supported-toolchains.md

@@ -0,0 +1,19 @@
+# Supported Toolchains
+
+vscode-swift supports several versions of the Swift toolchain.
+
+vscode-swift supports the following Swift toolchains:
+ * 5.9
+ * 5.10
+ * 6.0
+ * 6.1 (unreleased)
+
+The extension also strives to work with the latest nightly toolchains built from the main branch.
+
+Certain features of vscode-swift will only work with newer versions of the toolchains. We recommend using the latest version of the Swift toolchain to get the most benefit of the extension. The following features only work with certain toolchains as listed:
+
+Feature                  | Minimum Toolchain Required                     
+------------------------ | ------------------------------------- 
+lldb-dap debugging       | 6.0
+DocC preview             | 6.0
+

docs/test-coverage.md → userdocs/userdocs.docc/test-coverage.md

@@ -1,15 +1,17 @@
 # Test Coverage
 
+vscode-swift provides mechanisms to see coverage of your tests.
+
 Test coverage is a measurement of how much of your code is tested by your tests. It defines how many lines of code were actually run when you ran your tests and how many were not. When a line of code is not run by your tests it will not have been tested and perhaps you need to extend your tests.
 
 The Swift extension integrates with VS Code's Code Coverage APIs to record what code has been hit or missed by your tests.
 
-![](images/coverage-run.png)
+![](coverage-run.png)
 
 Once you've performed a code coverage run a coverage report will be displayed in a section of the primary side bar. This report lists all the source files in your project and what percentage of lines were hit by tests. You can click on each file to open that file in the code editor. If you close the report you can always get it back by running the command `Test: Open Coverage`.
 
-![](images/coverage-report.png)
+![](coverage-report.png)
 
 After generating code coverage lines numbers in covered files will be coloured red or green depending on if they ran during the test run. Hovering over the line numbers shows how many times each line was run. Hitting the "Toggle Inline Coverage" link that appears when hovering over the line numbers will keep this information visible.
 
-![](images/coverage-render.png)
+![](coverage-render.png)

userdocs/userdocs.docc/test-explorer.md

@@ -0,0 +1,9 @@
+# Test Explorer
+
+vscode-swift shows test results in the test explorer.
+
+If your package contains tests then they can be viewed, run and debugged in the Test Explorer.
+
+![](images/test-explorer.png)
+
+Once your project is built, the Test Explorer will list all your tests. These tests are grouped by package, then test target, and finally, by XCTestCase class. From the Test Explorer, you can initiate a test run, debug a test run, and if a file has already been opened, you can jump to the source code for a test.

userdocs/userdocs.docc/userdocs.md

@@ -0,0 +1,45 @@
+# vscode-swift
+
+@Metadata {
+   @TechnologyRoot
+}
+
+Language support for Swift in Visual Studio Code.
+
+@Metadata {
+    @DisplayName("vscode-swift")
+}
+
+This extension adds language support for Swift to Visual Studio Code, providing a seamless experience for developing Swift applications on all supported platforms. It supports:
+
+* Code completion
+* Jump to definition, peek definition, find all references, symbol search
+* Error annotations and apply suggestions from errors
+* Automatic generation of launch configurations for debugging
+* Automatic task creation
+* Package dependency view
+* Test Explorer view
+
+## Topics
+
+- <doc:installation>
+- <doc:supported-toolchains>
+
+### Features
+
+- <doc:automatic-task-creation>
+- <doc:debugging>
+- <doc:docc-previews>
+- <doc:language-features>
+- <doc:project-view>
+- <doc:test-coverage>
+- <doc:test-explorer>
+
+### Advanced
+
+- <doc:remote-dev>
+
+### Reference
+
+- <doc:commands>
+- <doc:settings>