[RFC] Swift DocC Integration

[matthewbastien]

Hello everyone! I’m creating this forum post to outline plans for implementing Swift DocC support in the Swift extension for Visual Studio Code (referred to in the rest of this post as vscode-swift). Feedback and suggestions are greatly appreciated and can either be left as replies on this forum post, or as comments on the relevant issue in the Swift extension GitHub repository.

The intent of this feature is to make documentation writing easier for anyone that’s using VS Code as their daily driver for Swift related work. For more information on Swift DocC and how it can help you maintain documentation for your Swift code, have a look at the swift-docc documentation.

Background

It is currently possible to generate DocC archives in VS Code using the terminal or tasks, but the process is quite cumbersome. Here is the step-by-step process that must be performed when starting from absolutely no documentation in a repository:

1. Add swift-docc-plugin as a dependency to the Package.swift for the project
2. Run a preview server with swift package preview-documentation
3. Open the link provided by the command output in the previous step in your web browser to see your documentation. This requires you to navigate to the page that you’re currently editing in order to see the result.
4. Every time you make changes you must then refresh your browser in order to see the results.

If you want to provide additional articles or tutorials then you also need to create a documentation catalog. This can be done with the docc init command or by manually creating an archive in Sources/<target-path>/<target-name>.docc.

The overall goal of this work is to simplify this process. This will involve:

1. Improving the documentation editing experience by providing a side-by-side preview of the documentation that is actively being edited.
2. Reducing the barrier to entry for creating documentation catalogs by providing a command Swift: Create Documentation Catalog.

Side-by-side Documentation Preview

Similar to the built-in VS Code Markdown preview editor, vscode-swift will provide a Swift documentation preview editor that will show how your documentation will look when it is generated. This will use swift-docc to generate the documentation archive and then update it in real-time as you type. Only a single preview editor can be open at any given time: whenever the active editor changes, the documentation preview editor will update to show the documentation for the markdown file being edited.

There will be two entry points for this editor:

1. A preview button in the editor toolbar
2. A command called Swift: Preview Documentation

Using either of these options will generate the documentation archive(s) within the repository and open a split-view editor that will show a preview of the documentation currently being edited:

It’s pretty straightforward to find and generated documentation on a per-target basis since all that the extension has to look for is a <target-name>.docc folder within each executable/library target source folder. It can also build the documentation archive(s) that it needs similar to how the swift-docc-plugin does it with its provided generate-documentation command.

However, it’s a little trickier for standalone documentation archives that can be located anywhere within the repository. For example, the swift-testing repository has documentation archives within its source folders as well as a top level Documentation folder. This use case will not be handled in the first pass of DocC integration, but may be implemented at a later date.

Create Documentation Catalog Command

In order to make it easier to create documentation catalogs, vscode-swift will provide a command called Swift: Create Documentation Catalog that will provide a set of guiding steps for creating a new documentation catalog in VS Code. The workflow will perform the following steps:

1. If there is more than one library or executable target within the Package.swift then vscode-swift will ask which target will have documentation created for it. This list will be multi-select capable and default to creating a catalog for each available target.
2. Ask which types of content will be added to the catalog. Currently, swift-docc supports creating two different types of documentation:
   1. Articles
   2. Tutorials

vscode-swift will then create the catalog(s) on disk populated with articles, tutorials, or both depending on user selection. Articles will contain the appropriate headings to be picked up by swift-docc automatically.