Wednesday, October 13, 2021

Swift-DocC Is Now Open Source

Franklin Schrans:

Swift-DocC encompasses tools and libraries to help developers write and generate documentation on many platforms, including macOS and Linux, with the goal to support all platforms with a Swift toolchain. The docc command line tool is already integrated in Xcode 13 and is architected in a way that can be integrated with other build systems such as SwiftPM. The open source project is composed of several components, some of which may be interesting in their own right for building other developer tools. The components include:

  • Swift-DocC — the documentation compiler tool that processes source file comments, standalone Markdown files, and related assets to produce a machine-readable JSON archive.
  • Swift-DocC-Render — a JavaScript-based web application that renders compiled DocC archives.
  • Swift-Markdown — a library that makes it easy to parse Markdown syntax in Swift.
  • SymbolKit — a Swift library that parses the symbol graph files emitted by the Swift compiler. These files encapsulate information about a module’s APIs, including their documentation comments.

The tooling understands the Swift documentation comment syntax already popular within the Swift community in stand-out tools like Jazzy and SwiftDoc, and in IDEs like Xcode. It adds some novel syntax features, too. For example, the double-backtick ``SymbolName`` syntax creates links between symbols.

Previously:

1 Comment RSS · Twitter

Benjamin Esham

I was happy to read in the Swift Forums post (https://forums.swift.org/t/announcing-swift-docc/52797) that support for static sites is coming sometime soon. It was pretty surprising that the initial version didn’t support that and, as many people have pointed out, it prevented DocC documentation from being hosted on GitHub Pages.

Leave a Comment