Automatically generate HTML specs and publish them via Github Pages

[kpet]

The HTML files for the various extensions currently in the repository were generated with various versions of asciidoc or asciidoctor and we do not currently check that the HTML files in the repository match the corresponding asciidoc source.

Following the introduction of an official toolchain in https://github.com/KhronosGroup/SPIRV-Registry/pull/247, we should add automation to guarantee that:

• All asciidoc sources are free from syntax errors (many of the files currently in the repo contain errors)
• The HTML files correspond to the asciidoc source and have been generated with the official toolchain or, better still, remove them from the repo and publish them automatically.

I think the following sequence of steps should get us there:

• [x] Remove footer in HTML files (#268). The footer contains the generation time and makes it impossible to diff in repo HTML files with files generated from the asciidoc in automation.
• [x] Fix errors in asciidoc sources and update all HTML files in the repository to use the official asciidoctor toolchain
  • [x] AMD: #290
  • [x] ARM: #269
  • [x] EXT: #290
  • [x] GOOGLE: #276
  • [x] HUAWEI: #289
  • [x] INTEL: #274
  • [x] KHR: #272
  • [x] NV: #275
  • [x] QCOM: #273
• [x] Automatically build HTML specs in CI and publish them via Github Pages #297
• [ ] Update Makefile to build non semantic specs #299
• [ ] Change README links to the github page location #300
• [ ] Remove HTML files from this repository

No longer doing:

• [x] Add automation to guarantee the correctness of asciidoc sources and that in repo HTML files match the asciidoc source and were generated with the official toolchain (#267)

[kpet]

2024/08/14 teleconference: consensus in the group to skip automatic checking of the HTML files as a step and transition directly to automatically publishing HTML specs via Github Pages and remove HTML files from the repo.

[bashbaug]

In case it helps other vendors updating their extension specs: One of the differences I noticed updating the Intel specs was that text in 'single quotes' is rendered as italics using asciidoc, but not always using asciidoctor. I couldn't figure out how to make the single quote method work reliably, and it's not documented in the asciidoctor docs, so I ended up switching everything to use _underscores_ for italics instead.

[wooyoungqcom]

SPV_EXT_mesh_shader.asciidoc seems broken. Quite a few tables are not correctly rendered when opened.

[Tobski]

I've just raised https://github.com/KhronosGroup/SPIRV-Registry/pull/290 for EXT and AMD extensions

[wooyoungqcom]

Thanks so much, Tobias I browsed the generated html files, they all look OK, now.

I tried generating them myself, and they were OK. The only complaint I got from asciidoctor that I used was

WARNING: SPV_EXT_physical_storage_buffer.asciidoc: line 112: id assigned to anchor already in use: VariablePointer

[Tobski]

Thanks so much, Tobias I browsed the generated html files, they all look OK, now.

I tried generating them myself, and they were OK. The only complaint I got from asciidoctor that I used was

WARNING: SPV_EXT_physical_storage_buffer.asciidoc: line 112: id assigned to anchor already in use: VariablePointer

Ah, that's a bit of a weird one, seems someone expected this to be read as plain text. Not sure how I missed it though! Thanks - I've pushed a fix now.

[bashbaug]

I noticed a few issues we may want to address after merging the changes to deploy to GitHub pages:

1. A bunch of extensions (but not all) include a "last modified date" towards the top of the file that gets populated based on the asciidoctor {docdate} attribute. Because we "touch" all of the files before building, this means that the "last modified date" is actually the "last build date". Do we want to "fix" this?
2. Our Makefile is currently only building the extension specifications and is not building the nonsemantic extended instruction sets. If we want to migrate our HTML specifications entirely to GitHub pages we'll want to enable the nonsemantic extended instruction sets, also.