{"id":32978,"date":"2021-06-30T16:56:54","date_gmt":"2021-06-30T20:56:54","guid":{"rendered":"https:\/\/mjtsai.com\/blog\/?p=32978"},"modified":"2021-07-02T13:55:46","modified_gmt":"2021-07-02T17:55:46","slug":"docc-is-unusable-for-open-source-projects","status":"publish","type":"post","link":"https:\/\/mjtsai.com\/blog\/2021\/06\/30\/docc-is-unusable-for-open-source-projects\/","title":{"rendered":"DocC Is Unusable for Open Source Projects"},"content":{"rendered":"

Jesse Squires<\/a> (tweet<\/a>, Hacker News<\/a>):<\/p>\n

The problem with DocC is hosting and distribution<\/a> — 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<\/code> package that includes all the HTML, CSS, JavaScript, and other resources for your documentation website. According to the docs on distribution<\/a>, you must host this .doccarchive<\/code> on your web server and implement various rules to rewrite incoming URLs. The example provided defines rules in an .htaccess<\/code> file for Apache.<\/p>

[…]<\/p>

DocC fails to deliver for this extremely popular use case — in my opinion, the most popular. DocC does not<\/strong> work with GitHub Pages — a significant<\/strong> 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<\/a> (Jekyll<\/a>, for example), which DocC does not produce. DocC creates a Vue.js<\/a> 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.<\/p>

[…]<\/p>

It feels like Apple built DocC for Apple<\/em>.<\/p><\/blockquote>\n\n

Paul Hudson<\/a>:<\/p>\n

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.<\/p>\n

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.<\/p><\/blockquote>\n\n

Update (2021-07-02): Helge Heß<\/a>:<\/p>\n

\n

We are going to look at the documentation archive produced, the good&bad and how to generate a static website.<\/p>\n<\/blockquote>","protected":false},"excerpt":{"rendered":"

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 .doccarchive […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"apple_news_api_created_at":"2021-06-30T20:56:58Z","apple_news_api_id":"c3bde5cf-d4d1-4ded-979b-bff075d7a937","apple_news_api_modified_at":"2021-07-02T17:55:51Z","apple_news_api_revision":"AAAAAAAAAAAAAAAAAAAAAA==","apple_news_api_share_url":"https:\/\/apple.news\/Aw73lz9TRTe2Xm7_wddepNw","apple_news_coverimage":0,"apple_news_coverimage_caption":"","apple_news_is_hidden":false,"apple_news_is_paid":false,"apple_news_is_preview":false,"apple_news_is_sponsored":false,"apple_news_maturity_rating":"","apple_news_metadata":"\"\"","apple_news_pullquote":"","apple_news_pullquote_position":"","apple_news_slug":"","apple_news_sections":"\"\"","apple_news_suppress_video_url":false,"apple_news_use_image_component":false,"footnotes":""},"categories":[2],"tags":[544,2089,164,524,31,2078,346,30,2077,991,71,96],"class_list":["post-32978","post","type-post","status-publish","format-standard","hentry","category-technology","tag-apache","tag-docc","tag-documentation","tag-github","tag-ios","tag-ios-15","tag-javascript","tag-mac","tag-macos-12","tag-open-source-software","tag-programming","tag-web"],"apple_news_notices":[],"_links":{"self":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/32978","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/comments?post=32978"}],"version-history":[{"count":2,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/32978\/revisions"}],"predecessor-version":[{"id":32990,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/32978\/revisions\/32990"}],"wp:attachment":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/media?parent=32978"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/categories?post=32978"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/tags?post=32978"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}