[HN Gopher] Apple's DocC is excellent, but unusable for open sou...
___________________________________________________________________
Apple's DocC is excellent, but unusable for open source projects
Author : ingve
Score : 83 points
Date : 2021-06-30 07:52 UTC (15 hours ago)
(HTM) web link (www.jessesquires.com)
(TXT) w3m dump (www.jessesquires.com)
| realityking wrote:
| Is 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.
| Brian_K_White wrote:
| There'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.
| Cthulhu_ wrote:
| When the alternative is a set of statically generated HTML
| pages that can be uploaded anywhere, yes.
| realityking wrote:
| It'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 wrote:
| But why require URL rewriting?
| ChrisMarshallNY wrote:
| That 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 wrote:
| Why would GitHub integrate DocC output? GitHub Pages doesn't
| have any other integrations, it's just a webspace for static
| content.
| pilif wrote:
| > 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 wrote:
| Static 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 wrote:
| DocC 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 wrote:
| I'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.
| sudhirj wrote:
| Aren'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 wrote:
| Not 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 wrote:
| Doesn't look like it, see
| 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 wrote:
| > 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 wrote:
| Pull the HTML and CSS out into a Jekyll layout.
| masklinn wrote:
| What 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.
| sudhirj wrote:
| Ok, last comment, not sure I want to argue about this. It
| looks like an application, but it's not. It's a bunch of
| HTML, CSS and JS packaged in a specific way (using its
| own spec), but it's not an executable. It's just arcane.
| It can be opened and expanded in the same way that a
| .epub book can be opened and hosted on a static website
| like GitHub Pages. It's not obvious or easy, but it can
| be done.
|
| Apple chose a packaging format, and they packaged it.
| It's not an executable. EPUB is a closer example. Can be
| opened, can be parsed, can be re-packaged to whatever
| format anyone wants.
| justinclift wrote:
| > 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.
| oefrha wrote:
| The 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 wrote:
| It'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 wrote:
| Oh 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.
| 3grdlurker wrote:
| I 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.
| blacktriangle wrote:
| I 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 wrote:
| If you use "monopoly" in the same sentence as "Apple" and
| somehow fail to conflate the two, humanity has truly lost all
| hope.
| doctoboggan wrote:
| Seems like a good opportunity for someone to setup a
| https://readthedocs.org like website that works with this new
| format. Maybe even readthedocs could start working with it.
| tpush wrote:
| Am I missing something? You can totally deploy a vue.js (or any
| JavaScript) on GitHub Pages.
| ddtaylor wrote:
| Agreed. 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 wrote:
| Sounds 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?
| kklisura wrote:
| > 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.
| pjmlp wrote:
| Actually this has existed since forever, back in 2000 that
| would either be a Java Applet or DHTML.
| misterS wrote:
| The Windows 95 ".chm" help pages [1] were basically HTML
| pages, displayed in an application embedding Internet
| Explorer. IIRC this lead to login exploits (since the login
| screen was able to show help pages).
|
| [1]
| https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help
| GeekyBear wrote:
| Microsoft Compiled HTML Help (.chm) has been the bane of all
| that is good and true ever since 1997.
| ChrisRR wrote:
| That doesn't make it better. We should be realising the
| mistakes of our past and improving with time
| pram wrote:
| Before that we would have had lovingly troffed manuals,
| checklists, man pages, binders, and libraries of books
| sitting in our spacious cubicle. Embrace tradition imo!
| sligor wrote:
| Maybe I'm wrong, but vue.js is just frontend js. So in theory
| it can be used in pair with a static server on backend side. So
| the problem here is surely not vue.js
| [deleted]
| noctune wrote:
| IMO, search is a pretty significant part of docs and I haven't
| seen a good way doing that without either javascript or a web
| server.
|
| But other than that, yeah, you don't really need JS.
| gumby wrote:
| You can just pass the query to an external search engine ,
| adding a `site:xxx` restriction.
| IshKebab wrote:
| Every time a site has done that I immediately go back
| because the experience sucks so much.
| gumby wrote:
| Better than most site search engines, which I admittedly
| a pretty low bar.
| est31 wrote:
| Rust's documentation uses javascript for search but it uses
| no js framework at all. IIRC the normal experience works
| without any JS. In fact it doesn't even use any traditional
| js tooling, allowing people to contribute to rustdoc without
| having to install npm.
| GrayShade wrote:
| > allowing people to contribute to rustdoc without having
| to install npm
|
| In the meanwhile, the crates.io team doubled down on Ember
| to attract front-end developers while presumably alienating
| a lot of other potential contributors.
| Zababa wrote:
| The crates.io website is weird, it seems out of place and
| not at the same level as the other part of Rust's
| ecosystem.
| jitl wrote:
| Recall that cargo and crates was built by one of the
| Ember founders, Yehuda Catz.
| GrayShade wrote:
| Were they? I don't see wycats among the crates.io
| contributors on GitHub. He did contribute a bit to cargo
| in 2015, though.
| nine_k wrote:
| A web app (as in SPA) can very well be a bunch of static files.
| I once wrote one at work, served off S3.
|
| Client machines are powerful enough now to do a lot, e.g. to
| scan a full-text search index packaged as a static file.
| KptMarchewa wrote:
| Wait, what? What do they need it for?
| Andrew_nenakhov wrote:
| To a boy with a hammer everything looks like a nail, I guess.
| planb wrote:
| Interactive Tutorials?
| 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 wrote:
| The tutorials are written manually in a SwiftUI-like
| script. It's a totally different thing from the docs auto-
| generator.
| planb wrote:
| Thanks 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]
| coldtea wrote:
| Search? Interaction? Collapsable sections?
|
| It's 2021.
| Zababa wrote:
| Rust has all of them with vanilla JS. The code is clear and
| easy to understand, and could be reused by other people
| easily. Here's an example: https://doc.rust-
| lang.org/std/vec/struct.Vec.html
| coldtea wrote:
| > _Rust has all of them with vanilla JS._
|
| Which is neither here, nor there.
|
| Since JS is required for those features (in the absense
| of a dynamic server backend), who cares whether it's
| bundled Vue.js or some hand-rolled vanilla JS?
|
| I'm sure some care. I'm not sure many care, and I'm even
| less sure that they have any valid reason to care besides
| a knee-jerk "bloat" reaction.
| akiselev wrote:
| There is a _quantitative_ difference between a folder
| with some HTML + other assets and a project that requires
| a specific v8 runtime wrapper and its own build pipeline
| to generate the aforementioned artifacts.
|
| My grandmother knows how to (and does) use the former.
| The latter guarantees I'll always have a job.
| ironmagma wrote:
| There is no way anyone in their right mind would call
| main.js[1] easy to understand. It's basically complete
| chaos. Guillaume is making a good effort to clean up this
| inherited code slowly, but the interactions are still
| kind of broken and will be until this code is rewritten
| in a sane pattern such as MVU. FWIW, I have been working
| towards this for the past year.
|
| [1] https://github.com/rust-
| lang/rust/blob/master/src/librustdoc...
| Klonoar wrote:
| None of these require a framework.
| est31 wrote:
| collapsible sections are possible using css only, or using
| the details tag (not even css needed). As for search, you
| don't need a framework for that.
| [deleted]
| SpaghettiX wrote:
| I 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/
|
| 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-d...
| Zababa wrote:
| Thanks for the example. I'm noticing a ~1 second delay for a
| page load after I click something. That seems a bit much.
| sydthrowaway wrote:
| "Apple product is incompatible with Microsoft service"
| ChrisRR wrote:
| Apple is being obtuse as always with their massive NIH syndrome
|
| For every step forward they take, they take 2 back
| thrower123 wrote:
| It sounds like they've reimplemented either Microsoft's old
| HLP/CHM, or epub, but badly.
| drdude wrote:
| I 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]
| greatgib wrote:
| The 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 wrote:
| A 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 wrote:
| There'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.
| joosters wrote:
| In summary, the documentation tool is no good for open-source
| projects because it doesn't work with a non open-source website?
| pilif wrote:
| it 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 wrote:
| Those 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.
| Brian_K_White wrote:
| There are many different reasons a thing can be considered
| unusable. This certainly qualifies. The problem isn't
| specific to github.
| yarcob wrote:
| This 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.
| realityking wrote:
| > 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)
| illustrates this quite nicely. While Netlify has some
| Function-as-a-service capabilities DocC uses none of that.
| pilif wrote:
| > 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 wrote:
| I 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 wrote:
| I'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 wrote:
| I 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.
___________________________________________________________________
(page generated 2021-06-30 23:02 UTC)