During WWDC 21, Apple announced that they would be open sourcing documentation tooling (DocC) that’s used to build and provide documentation within Apple. At the tail end of October 2021, the initial version of DocC was released — available on Github, scattered through multiple repositories:
The initial release of DocC is primarily oriented around providing documentation for libraries and frameworks. It isn’t quite useful for documenting the internals of apps (yet!), but it’s getting closer. Some developers are waiting for features they see as critical before adopting DocC. I suspect the most sought-after feature is the ability to output something that can be dropped into a directory and directly hosted — such as rendering the documentation so that it can be published through Github Pages.
With this feature, and some other recent improvements and plans, including some outside of DocC, I am looking forward to adding documentation to a few libraries I’m using, but which haven’t yet adopted DocC.
Unfortunately, Apple’s documentation on what you do to adding documentation to an existing swift library (say, one provided by
Package.swift) has some trouble — it’s so highly focused on adding documentation using Xcode, and to when you have an Xcode project, that it heavily neglects the details for settings things up with package-only swift libraries. There’s a good article by Keith Harrison from this summer (at https://useyourloaf.com/blog/xcode-docc-getting-started/) that helps, but also leans heavily on using Xcode.
If you want to build the documentation through just Package.swift (for instance, if the library has no
xcodeproj file), then make sure the Package.swift tools version is at 5.5:
Where you put the documentation is important as well. There’s a one-liner from the Apple’s article:
For Swift packages, place the documentation catalog in the same folder as your library’s source files for DocC to associate the catalog with the library.– Documenting a Swift Framework or Package
When you’re not working in Xcode, this means adding a directory in the sources directory of your package with an extension
.docc on it. For example, when I drafted a documentation stub pull request for automerge-swift, I used the package name
automerge.docc, not the repository name
automerge-swift.docc. The name of the directory doesn’t appear to matter, but I like Keith’s suggestion of having it match the package name. Within the
.docc directory, include at least one markdown file that has at the top of a special marker that lines up with the name of the package. In my documentation PR for automerge-swift, I ended up with the following structure and files:
You can get Apple’s templates by making a (throw-away) Xcode project, adding documentation files to it, and copying them out – but I thought I’d include a few examples for anyone else looking on the web for the quick detail.
The template for the overall catalog:
# ``YourPackageNameHere`` One line summary ## Overview Short (a paragraph, maybe two) overview of your library. ## Topics ### Group - <doc:AnArticle>
A few notes about this template:
- The name at the top should match the name of your swift package, surrounded by the double-back ticks.
##headings are the major groupings. You can provide additional organization with
###, but don’t bother with sub-sub-headings (#### or more). Its legit markdown, but ignored by DocC.
- If DocC can’t find a symbol reference that you have in your markdown, or a link to the relevant
<doc:>article, then it may just pass on displaying it. In some cases, (links to symbols using the “ syntax) a misspelled symbol may be presented as you provided it, in a fixed-width font, but not have a link.
- The doc link above references the name of the article’s markdown file – not the title within it. Although to keep yourself sane, I’d recommend keeping the title and header pretty much identical.
And to match that, here’s a quick and dirty template for an Article, loosely based off the one Apple provides within Xcode:
# Article One sentence overview/abstract introducing the article ## Overview Introductory paragraph(s) ## How to do something interesting Your content ### section heading Your content
Third, there’s an template that Xcode is calling an Extension, which you can use to add additional detail onto an existing symbol – it incorporates what you included with the symbol, and allows you to add more – but external to the documentation in the source. There’s a nice detail of this template within Apple’s article Adding Structure to Your Documentation Pages.
While you can edit and set these up with any text editor, you get a notable win when you use Xcode to editing these files.
- The DocC compiler provides nice fixit’s – notes about what’s wrong – when it can’t find or link to a symbol after you tried to build the docs with Product > Build Documentation using Xcode.
- Xcode provides some very handy symbol code-completion capabilities within Xcode that you’d otherwise have to guess or learn through trial and error.
At some point, hopefully in the near future, you’ll be able to render out a bunch of static HTML with your documentation. For now, the easiest way to iterate and see the feedback is by building the docs through Xcode. The shortcut keybinding (Shift-Control-Command-D) is a finger-bender, but after Xcode builds the documentation, you immediately see the results in the documentation window of Xcode.