I was very excited at this year’s WWDC when Apple announced DocC, their new “Documentation Compiler” tool that generates documentation from comments in your source code. Unfortunately, it’s not going to work for the majority of open source authors.

A brief history

Many folks are probably unaware that the company shipped and maintained a similar tool before, the now-defunct HeaderDoc, which had a final stable release in 2009. Eventually, Tomaz Kragelj wrote and released an open source replacement called AppleDoc, which became the standard way for Apple platform developers to publish documentation for their open source libraries. While AppleDoc began to languish from a lack of regular contributors, Swift was announced in 2014. AppleDoc was soon replaced by another community-built tool, Jazzy, authored by JP Simard and maintained by various contributors. There is also a lesser-known library called SourceDocs, authored by Eneko Alonso. More recently, Mattt took another approach at solving this problem with swift-doc. The community has mostly centered around Jazzy. After all these years of the open source community filling in the gaps and building their own tools, Apple finally announced a new first-party solution for generating documentation.

Introducing DocC

Overall, there are many things to like about DocC. The integration with Xcode’s Editor and Documentation Viewer is excellent. There is a command-line tool included, xcodebuild docbuild, which you can invoke from automation scripts. The overall workflow for generating and exporting documentation is built-in to Xcode and its build process, making it very easy to use. Finally, the documentation itself looks incredible. It uses the same styling as Apple’s official documentation, making it very familiar to any Apple platform developer. The design is clean and well-organized. You can even include supplemental resources, including interactive tutorials.

The problem with DocC is hosting and distribution — arguably the most important aspect of this type of tool! What’s the point of generating amazing docs for your library or SDK if you can’t easily distribute or publish them for your users? When you run DocC, it produces a .doccarchive package that includes all the HTML, CSS, JavaScript, and other resources for your documentation website. According to the docs on distribution, you must host this .doccarchive on your web server and implement various rules to rewrite incoming URLs. The example provided defines rules in an .htaccess file for Apache.

# Enable custom routing.
RewriteEngine On

# Route documentation and tutorial pages.
RewriteRule ^(documentation|tutorials)\/.*$ MyProject.doccarchive/index.html [L]

# Route files and data for the documentation archive.
#
# If the file path doesn't exist in the website's root ...
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

# ... route the request to that file path with the documentation archive.
RewriteRule .* MyProject.doccarchive/$0 [L]

The docs suggest keeping it up to date using a continuous integration workflow that generates and copies your .doccarchive to your web server. For additional information on hosting, see this post on Hosting DocC Archives by Joseph Duffy. Examples provided include Netlify, Vapor middleware, nginx, and Apache.

There is one last quirk. The default output location for the DocC archive is buried in Xcode’s DerivedData/ directory, which is… certainly a place to put it. Apple seems to think that’s a good directory for a lot of things, but I strongly disagree. Luckily, you can specify another derived data directory location when using xcodebuild docbuild.

Ignoring prior art

So far, this may not seem like an issue — unless you are an open source author and maintainer like me. There is a particularly vibrant community of open source iOS developers on GitHub. Most open source communities have standardized on GitHub, but especially the Apple developer community — everyone hosts their projects on GitHub. Because of that, we all host our documentation alongside our projects using GitHub Pages. It is an incredibly valuable product and service that is easy to use. First, you generate your docs — we all use Jazzy — then you place them in docs/ on your default branch. For an example, see the popular Alamofire library and its documentation. I also wrote about this in 2016.

This is what nearly everyone does: host your project on GitHub, generate docs using Jazzy, and host your docs using GitHub Pages. In fact, no open source projects immediately come to mind that do not implement this workflow. I’m sure those projects exist, but they are the exception, not the norm. Even Apple hosts their open source projects on GitHub now and uses GitHub Pages for the Swift Evolution proposal site. More ironically, some teams at Apple actually use Jazzy and publish docs on GitHub Pages like I’ve described for some of their open source Swift packages, like SwiftNIO (see the docs here).

DocC fails to deliver for this extremely popular use case — in my opinion, the most popular. DocC does not work with GitHub Pages — a significant barrier for adoption for essentially all open source projects in the Apple developer community. I experimented with some hacks, but was unable to make DocC do what I need. The GitHub Pages server environment is a bit opaque to the user, but it is intended for hosting static sites (Jekyll, for example), which DocC does not produce. DocC creates a Vue.js web app and requires that you run your own web server to dynamically serve it, as described above. The process feels clunky and overcomplicated compared to GitHub Pages.

I badly want to use DocC. I would love to be able to use DocC for all my projects — but I cannot in its current form, nor can most anyone else. Unless, of course, you want to setup, maintain, and pay for a web server to host docs for your open source project that you work on for free. Who is going to do that!? Again, Joseph Duffy provided great examples for hosting, but how practical is it really? You would have to setup a new site for hosting the docs for each project you maintain. That is not tenable. Generating docs with Jazzy and hosting via GitHub Pages works great. Plus, it’s free.

Unless something significant changes in DocC, I will continue using Jazzy. I do not have much of a choice, sadly. At the very least, it would be nice if DocC provided an option to generate a static site instead. Aside from working with GitHub Pages, a static site would hopefully require much less JavaScript, of which there is currently a seemingly excessive amount. I think Paul Hudson captured the core issue well:

As things stand, the generated documentation is effectively a sealed box […] The web pages are also very heavy on the JavaScript and honestly I’m not sure why – the reference documentation and articles are simple beasts, and if DocC could flatten them to plain HTML then I imagine the rewrite rules would just go away. At the same time, Apple’s own documentation system is completely inaccessible with JavaScript turned off, so I don’t hold out a great deal of hope here.

For whom is this intended?

This brings me to the final question at hand — who is this tool for? I’m not being sarcastic. I can think of two main groups of users for DocC: individual open source library authors and bigger companies that provide closed-source SDKs. I’m curious — what did the DocC team envision for this tool? It certainly does not feel like it was written for our community of open source library authors, and that is beyond frustrating and disappointing.

Could companies that distribute popular SDKs make use of DocC? I’m thinking of SDKs like Paddle, Segment, Firebase, and Facebook. However, it seems unlikely that any of these companies would use DocC. They (obviously) already have custom tooling and workflows to generate and host their own custom-branded documentation. They are not going to use DocC unless it can be heavily themed, and even then that’s probably not enough for them to switch from their current setup. Paul Hudson also points this out:

[…] the Apache rewrite rule references a theme-settings.json file, which suggest some customization is going to come, but I don’t know to what extent. I can imagine bigger companies wanting their corporate branding integrated, or their regular site navigation.

It is clear that the team behind DocC worked hard on this tool — it shows. Like I mentioned at the start, the breadth and depth of what DocC offers is impressive. Still, it feels like the creators were somewhat clueless about what third-party developers actually need, which seems to be a trend. It feels like Apple built DocC for Apple. We’ve been using Jazzy with GitHub Pages since 2014 — even CocoaDocs was using Jazzy. How could one overlook that when creating a new tool?

This would not be so upsetting if Apple’s developer relations were not abysmal — not to mention, “the Elephant” at WWDC. For years, our community has built and maintained its own tools that work exactly how we need them. Then Apple (finally!) releases a first-party tool that is amazing for addressing 90% of the problem, but omits the most important 10% of the solution.

And so, we are unable to use the could-have-been-so-great tool that the highly-paid software engineers at Apple built because it just barely misses the mark. We are left in stark contrast to continue maintaining our community-built tools, primarily with unpaid labor.

To be open source

Finally, Apple mentioned that DocC will be open sourced later this year. Some folks in the community seem optimistic about what that means for the future of DocC — maybe some determined, enthusiastic open source contributor will submit a patch that implements a “static site mode” for DocC. But at that point, what have we actually gained?

Update 30 June 2021

This post was updated to include mentioning SourceDocs, and that Apple actually uses Jazzy and GitHub pages for some of its Swift packages, like SwiftNIO.

Additional updates:

JP and friends maintaining Jazzy have opened an issue to track adding support for ingesting DocC archives as input, instead of relying on SourceKitten. So interestingly, what we may end up with is a community-built tool on top of DocC that provides the static site functionality we need.

Sven Schmidt who maintains the Swift Package Index with Dave, suggested on Twitter that the Swift Package Index could conceivably generate and host DocC documentation. That would be pretty awesome in my opinion — it would be CocoaDocs 2.0!

I think what I’m realizing is that community tooling is never going to be replaced by what Apple provides.

Update 11 July 2021

Helge Heß has written a post about converting DocC archives into static HTML sites. You can find the project on GitHub. It is currently still a work-in-progress, but a promising start.

Update 03 December 2021

Good news! There’s a new thread on the Swift forums to discuss an official solution to support hosting DocC archives in static hosting environments, like GitHub pages.

Update 30 December 2021

There’s more good news to share! And hopefully this will be the final update to this post. A pull request (#44) to add static hosting support to DocC has merged into the main branch of the swift-docc repo. A second pull request (#56) is currently open to pick the changes into the release/5.6 branch, which matches the main Swift repo’s release/5.6 branch. So, I believe we should expect an official release of DocC with support for static hosting alongside the release of Swift 5.6. However, there’s been no official post on Swift.org about the timeline or roadmap for Swift 5.6. It will likely be summer 2022.

Further Reading