Automatically generating spec HTML

[timdp]

So it's probably a bit early for this, but I wanted to get the ball rolling so we don't have to rush things later on. Friendly warning: it's going to get technical.

Currently, we have index.html checked into Git, and by merely ticking the GitHub Pages checkbox, we got a nice URL for our living document. That's awesome.

However, it'd actually be great if we could avoid having to check index.html into Git. Traditionally, you wouldn't check in built artifacts (in this case index.html). They're redundant since they can be reproduced from the source code, and they can diverge for all sorts of reasons. Especially when people start creating more pull requests for SIVIC, this is going to cause headaches, since index.html will either be part of each diff, or we'll have to instruct people to exclude it.

I've just created #14 to avoid divergence caused by people using different versions of Bikeshed, but the redundancy problem remains.

Now, GitHub Pages is of course a very elegant and lightweight solution, and it just happens to require checking in index.html. Ideally, GitHub would understand Bikeshed and just build the HTML for us behind the scenes. Unfortunately, they only have that feature for the Jekyll format, not for Bikeshed, and I don't think they're looking to change that anytime soon.

Since we're using WHATWG's setup for inspiration, I took a quick look at what they're doing. They seem to have quite a bit of tooling around this. Specifically, there's a separate whatwg/html-build repository purely for the build scripts. The build artifacts end up in an output folder on the user's machine, which is not checked into Git. I assume they periodically generate the folder on a build server.

In an ideal world, I think we would have two things automatically generated for us:

• Versioned builds: permanent labeled versions of the spec.
  Example: interactiveadvertisingbureau.github.io/SIVIC/1.0/

• Nightly builds: rebuilt daily or upon every commit, to represent the living document.
  Example: interactiveadvertisingbureau.github.io/SIVIC/latest/

I'm happy to suggest ways to approach all this and coordinate the effort to get it set up. I first wanted to get some opinions though. Maybe some of it has already been discussed?

[pietermees]

@timdp this makes total sense for me. We probably want

• add gitignore for the html build
• Set up build server that runs when something is checked in
• Deploy generated builds to s3?
• Have versioned urls that serve the right commit build?