Static Renderer

DocC needs to have an option for generating a static site. JavaScript is unnecessarily heavy for the purpose, and the current story for hosting documentation is unnecessarily complicated. It should be possible to completely disable JavaScript without compromising the ability to browse the default documentation.

In particular, I think there should be a substantial amount of focus on the ability to automatically generate documentation compatible with services such as GitHub Pages. I think a lot of people would be thrilled if a CI job could automatically generate documentation for any SPM-compatible repo.

I’m not saying it should explicitly rely on GitHub or anything. Generating static HTML and CSS would be sufficient.

13 Likes

+1! It’d be lovely to be able to just generate a static site and host that on, eg, GitHub Pages or Netlify.

3 Likes

DocC may contain Tutorials, which in a form or another require JavaScript. If an option to generate only static and "JS-free" documentation were available, would those be prevented entirely?

If I'm not mistaken, the DocC team separated the generation of metadata from the renderer process (great!), which – I assume – means that you're free to provide your own renderer built entirely from scratch (fully static, JS agnostic, built with ReactJS instead of VueJS, etc.), so customizing options could be of secondary importance.

Simply require JavaScript where absolutely necessary, and nowhere else. Tutorials should probably require it, but that isn’t the main purpose of documentation.

If you want a good example of how to do that, disable JavaScript and reload this page.

2 Likes

And AWS S3 static hosting

1 Like

Specifics are definitely not DocC’s problem. Simply not requiring JavaScript to be usable would be enough for other tools to handle the rest.

1 Like

It’s on the list

5 Likes

Ah, my mistake. Sorry about that.