DocC Is Unusable for Open Source Projects
Jesse Squires (tweet, Hacker News):
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
.doccarchivepackage that includes all the HTML, CSS, JavaScript, and other resources for your documentation website. According to the docs on distribution, you must host this.doccarchiveon your web server and implement various rules to rewrite incoming URLs. The example provided defines rules in an.htaccessfile for Apache.[…]
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.
[…]
It feels like Apple built DocC for Apple.
As things stand, the generated documentation is effectively a sealed box – 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.
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.
Update (2021-07-02): Helge Heß:
We are going to look at the documentation archive produced, the good&bad and how to generate a static website.
5 Comments RSS · Twitter
Blimey, all this kvetching, for want of a simple web server. Really?
Disclosure: Not Swift coder. Tinker with server software for an encore. I'm probably biased (or wrong, or both).
Jesse's headline seems a bit sensationalist. They're not wrong that GitHub Pages is rather common, and that its URL rewrite options are limited, but to go from that to "unusable for OSS" is quite a stretch.
>It feels like Apple built DocC for Apple.
Given that the author points out alternatives… so what?
@Sören:
> Jesse's headline seems a bit sensationalist. They're not wrong that GitHub Pages is rather common, and that its URL rewrite options are limited, but to go from that to "unusable for OSS" is quite a stretch.
Hair-splitting the definition of unusable or confusing possible with usable? GitHub is the biggest OSS hosting company by a wide margin these days, so that you can currently assume OSS ≈ GitHub. All arguments why DocC on GitHub Pages has a bad user experience were already laid out so I won’t repeat them here.
>> It feels like Apple built DocC for Apple.
> Given that the author points out alternatives… so what?
Given that Apple has presented DocC this year to the public… so what? Maybe they could’ve waited for another year or put a disclaimer on it about its current state?
>Hair-splitting the definition of unusable or confusing possible with usable?
No, I think that's a very misleading definition of "unusable".
> GitHub is the biggest OSS hosting company by a wide margin these days, so that you can currently assume OSS ≈ GitHub.
And tons and tons of OSS projects on GitHub do not use GitHub Pages.
>Given that Apple has presented DocC this year to the public… so what? Maybe they could’ve waited for another year or put a disclaimer on it about its current state?
Sure, or they could've done what they actually did do, which is release something not everyone is happy with.
It's not like they presented it at the keynote as the greatest thing ever. If I'm not mistaken, they didn't mention it at all. (They might have at the state of the union. But even so, it's hardly a tentpole feature.)
Don't we have bigger fish to fry than "Apple released a static site builder that requires rewrite rules, which some hosting services don't support"?
> hosting and distribution — arguably the most important aspect of this type of tool
I agree. The way DocC's web portability (or lack thereof) has overshadowed the extension to XCode's Developer Documentation shows how important people think this is.
Personally, I'm just excited to get native documentation for my imported Swift packages in XCode.
