Apple's DocC is excellent, but unusable for open source projects

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. More recently, Mattt took another approach at solving this problem with swift-doc. 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.

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?

Further Reading

from Hacker News https://ift.tt/2SAUv02