8 ms·
Apple's DocC is excellent, but unusable for open source projects
- joosters 5y agoIn summary, the documentation tool is no good for open-source projects because it doesn't work with a non open-source website?
- pilif 5y agoit doesn't work with any kind of static web hosting which is a shame given that it's all static content anyways. The scripts could be adapted to work without requiring URL rewriting on the server. The second complaint is about styling which currently doesn't seem possible. If you're a project of any considerable size, you probably will want your docs to be branded in some way which is not possible either ATM.
- joosters 5y agoThose are certainly issues, but note that they have nothing to do with the alleged main point of the article, in that they make it unusable for open source projects. Quite the opposite, they are unrelated to the licensing at all. I think it is a fair criticism to point out that the author seems unhappy about a non-OS website yet they somehow think this is an OS issue.
- yarcob 5y agoThis is not about licensing. The problem is that DocC is incompatible with the current tools that many Open Source projects use. Sure, you could use DocC for an OS project and set up your own server to host it. It's probably pretty cheap to do that on a VM. It would require just a little bit of learning about web hosting and would require minimal maintenance. But why would anyone do that when Github pages is completely free, requires zero maintenance, and everyone knows how to use it already? A lot of small Open Source projects currently use Github + Github pages for hosting docs because it is such a convenient offering. If you want to use DocC, you have to look for something else.
- Brian_K_White 5y agoThere are many different reasons a thing can be considered unusable. This certainly qualifies. The problem isn't specific to github.
- realityking 5y ago> it doesn't work with any kind of static web hosting which is a shame given that it's all static content anyways. As far as I can tell, that’s not true. The output is completely static and just requires some very basic URL rewrites. The Netlify config in the linked blog post (https://josephduffy.co.uk/posts/hosting-docc-archives https://josephduffy.co.uk/posts/hosting-docc-archives) illustrates this quite nicely. While Netlify has some Function-as-a-service capabilities DocC uses none of that.
- pilif 5y ago> As far as I can tell, that’s not true. The output is completely static and just requires some very basic URL rewrites. My understanding of static webpages is that there's zero processing happening server-side. "Basic URL rewrites" counts as processing in my book
- djxfade 5y agoI have hacked "URL rewriting" on Github, bu having a custom 404 page, that rewrites the URL as a query parameter. And then in the app just use the history api to take that query paramenter and replace history without an actual reload.
- tombl 5y agoI've deployed SPAs on GitHub Pages before, and you can just rename the index.html to 404.html and the site will function just as normal with no modifications.
- realityking 5y agoI think that’s an arbitrary line you’re drawing. Every webserver does some URL rewriting, otherwise you wouldn’t be able to to use /docs, /docs/ and /docs/index.html. The difference is just that this requires some more custom rewriting rules to facilitate being a single page app. I personally even disagree with that architecture, I think it’d be better to pretender the content for all pages (like, e.g., Gatsby does) but I wouldn’t call it not a static page.
- realityking 5y agoIs setting up a (free) Netlify site really such a big barrier to entry? GitHub really has the community spoiled with their big bundle of free services. Anyway, I suspect there’s a reasonably good chance for GitHub to pick this up eventually as a feature for Pages.
- Cthulhu_ 5y agoWhen the alternative is a set of statically generated HTML pages that can be uploaded anywhere, yes.
- realityking 5y agoIt’s still just statically generated HTML pages (+ some client side JavaScript). It only requires a webserver with a minimal amount of configurability for URL rewriting and redirects.
- tsimionescu 5y agoBut why require URL rewriting?
- Brian_K_White 5y agoThere's no excuse for the need. It's not about github. github is just the real world and most visible example, but the problem is general. For most of my own small projects the docs are nothing but the README.md, and if the only way to make better docs required setting up a web server for each one just to host it's docs, they never will be more than the readme. It's completely unreasonable to require a dedicated server to host some documents, which in themselves wouldn't and don't require any such thing.
- sudhirj 5y agoAren’t all the problems solvable with a few scripts? The complaint seems to be that the archival format isn’t directly compatible with GitHub pages, and it’s stored in an odd folder, but should be possible to copy and extract out into any format using a script.
- masklinn 5y agoNot if the documentation is shipped as a web application which dynamically generates incorrect urls you have to rewrite on the server side. Which seems to be the case.
- sudhirj 5y agoDoesn't look like it, see https://github.com/JosephDuffy/DocC-netlify https://github.com/JosephDuffy/DocC-netlify which is the example linked in the article. The author treating the archive as a folder with static files in it, and using the URL rewriting DSL to do full service.
- masklinn 5y ago> and using the URL rewriting DSL That’s exactly the issue outlined in the article. Now how do you do that if you don’t have a handle on url rewriting? What are your “a few scripts” going to do exactly?
- sudhirj 5y agoPull the HTML and CSS out into a Jekyll layout.
- masklinn 5y agoWhat HTML and CSS? It’s a giant web application, are you goings to crawl the entire thing using puppeteer to extract the content then make up pages and synthesise links? All the HTML page does is load the JS application, and tell you to get fucked if you don’t have js enabled.
- kklisura 5y ago> DocC creates a Vue.js web app This is the main problem with web that people are raising. Something as simple as documentation, that obviously should be a collection of static pages, is now a web application. You don't need React, Vue, Angular, Ember, etc. What you're building now might not be web application.
- KptMarchewa 5y agoWait, what? What do they need it for?
- Andrew_nenakhov 5y agoTo a boy with a hammer everything looks like a nail, I guess.
- planb 5y agoInteractive Tutorials? https://developer.apple.com/documentation/docc/building-an-interactive-tutorial https://developer.apple.com/documentation/docc/building-an-i... I found that via web search, but I couldn't find a demo anywhere online...
- pornel 5y agoThe tutorials are written manually in a SwiftUI-like script. It's a totally different thing from the docs auto-generator.
- planb 5y agoThanks for clarifying, but are you sure? On the very page I mentioned, there's a link at the bottom: "Distributing Documentation to External Developers" and on that page it says: "Share your documentation directly with Xcode users or host it on a web server." Sounds to me like you build that documentation using the SwiftUI-like DSL, but it is distributed in the DocC package.
- deleted 5y ago[deleted]
- sydthrowaway 5y ago“Apple product is incompatible with Microsoft service”
- ChrisRR 5y agoApple is being obtuse as always with their massive NIH syndrome For every step forward they take, they take 2 back
- ChrisMarshallNY 5y agoThat sucks. I was looking forward to using DocC, but the not working with GH Pages is a showstopper. I hope that Jazzy keeps going. I suspect that GH will end up integrating DocC output into GH Pages.
- mark_and_sweep 5y agoWhy would GitHub integrate DocC output? GitHub Pages doesn't have any other integrations, it's just a webspace for static content.
- pilif 5y ago> it's just a webspace for static content. that's not true. They do run sites through Jekyll on each commit. It's very possible they could add explicit support for rendering docarchives.
- est31 5y agoStatic in this context means that requests by visitors have no influence on the site's content. As for Jekyll, it's a static site generator. The output is still static content.
- realityking 5y agoDocC is also static. It just requires some simple URL rewriting. It could probably even done by putting Cloudflare in front of of GH Pages.
- ChrisMarshallNY 5y agoI'll have to study this a bit. If I can add a simple index.html file, one step up, that redirects into the bundle, that might work.
- 3grdlurker 5y agoI suppose there’s merit in the complaints from an OSS contributor’s standpoint, but yes, it seems like the current target market is companies with closed-source SDKs. Which isn’t a bad thing if this is MVP1, and I do expect improvements in the future.
- doctoboggan 5y agoSeems like a good opportunity for someone to setup a https://readthedocs.org https://readthedocs.org like website that works with this new format. Maybe even readthedocs could start working with it.
- tpush 5y agoAm I missing something? You can totally deploy a vue.js (or any JavaScript) on GitHub Pages.
- ddtaylor 5y agoAgreed. The only thing you'll miss out on are a few interactions with vue-router, basically your URLs will go from this: foo.com/blah To this: foo.com/#/blah The obvious reason being that without those URL rewriting rules the client would do a real HTTP request for "/blah" and problems ensue. Note that the problems won't actually occur until after the user tries to refresh the page or similar because the entire URL bar is being hijacked by window.location management.
- jbergstroem 5y agoSounds like a good use case to support natively via cloudflare workers / their tool wrangler; which makes hosting less relevant. I know cloudflare is a no-go for many, but for the rest of us it makes sense. Could probably be hosted fully on their pages too?
- thrower123 5y agoIt sounds like they've reimplemented either Microsoft's old HLP/CHM, or epub, but badly.
- greatgib 5y agoThe content of the rant is stupid, in fact, if you read this post, DocC is "unusable," with "github" and the specific workflow of the author, not specifically with "open source" projects. But, that being said, there are countless documentation from code formatter, I don't really see what particularity DocC has to be considered as excellent.
- yarcob 5y agoA very large number of open source projects use a workflow similar to the author: Source code on Github, documentation on Github pages. If a new tool doesn't work with that setup, nobody will use it.
- oefrha 5y agoThere's also a large, and probably growing number of open source projects hosting documentation on Netlify/Vercel. Somebody's definitely going to use it, and if it has enough other advantages, people will notice and migrate. And GitHub might one day support path-based SPAs, it's old news at this point. I still remember GitHub Pages being an https holdout for many years.
- oefrha 5y agoThe problem here is GitHub Pages doesn't support path-based SPA, i.e., it doesn't support rewriting non-asset URLs to site index. I won't argue for or against using an SPA (without SSR, too) for documentation, but this is certainly one of the most annoying limitations of GitHub Pages in 2021, generally speaking.
- tombl 5y agoIt's a hacky workaround, but by naming your HTML file 404.html it functions just as a regular SPA supporting webserver would. It does send a 404 where a normal webserver would send a 200, but it doesn't cause any problems from my testing.
- lf-non 5y agoOh wow. Don't do this. I have noticed multiple times that when I navigate to some documentation site brave shows this bar that page does not exist and whether you want to access it on archive.org. But the site below is perfectly functional. I always thought that this was some weird server misconfiguration causing 404 even if content is available ... Never guessed it was a hack to enable SPA routing.
- SpaghettiX 5y agoI spent a few hours (and asked on Stack Overflow [0]) simply trying to "see" the the output of DocC was (the web app documentation). You can see an example (documenting an example app from WWDC) which I'm hosting here: https://xcode-docc.netlify.app/documentation/ https://xcode-docc.netlify.app/documentation/ Even to get this far, it was complicated, and really hope Apple listens to the community so we can have statically generated documentation. [0] https://stackoverflow.com/questions/68048298/running-xcode-docc-without-apache-server-htaccess https://stackoverflow.com/questions/68048298/running-xcode-d...
- Zababa 5y agoThanks for the example. I'm noticing a ~1 second delay for a page load after I click something. That seems a bit much.
- deleted 5y ago[deleted]
- blacktriangle 5y agoI read that whole article as "Github is unuseable for open source projects." Seriously I get that people like Github, okay. But the way everybody is rushing to hand Github a monopoly not just on git hosting but the entire open source workflow is terrifying.
- smoldesu 5y agoIf you use "monopoly" in the same sentence as "Apple" and somehow fail to conflate the two, humanity has truly lost all hope.
- justinclift 5y ago> Because of that, we all host our documentation alongside our projects using GitHub Pages. Er... GitHub Pages only serves content over IPv4. So is completely unusable for large portions of the world.
- drdude 5y agoI wish we had documentations in the form of man-pages even with diagrams as ascii art, and then everything is readable, searchable, highlighted, ...etc from the terminal. I don't want to pick my hands off my keyboard and pull the mouse (or touchpad, or using a thinkpad nip) just to view, read, and browse the docs.
- deleted 5y ago[deleted]
- PostThisTooFast 5y ago"even CocoaDocs was using Jazzy. How could one overlook that when creating a new tool?" Apple pretends that nobody did anything until Apple came along Nobody had their music organized into directories. Nobody had their pictures organized. Nobody WANTED their notes organized. Welcome to Apple's detachment from the real world. Now you can begin to understand "thin, elegant" phones that must be buried in bulky, tacky cases to withstand being used for their primary purpose. Cue the fawning suck-ups in the press, who give Apple a free pass on all of its anti-customer bullshit. When you tolerate shit, that's all that becomes available to you.