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 #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:

• Remove footer in HTML files (Disable asciidoctor footer and enable failure on errors #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.
• Fix errors in asciidoc sources and update all HTML files in the repository to use the official asciidoctor toolchain
  • AMD: Regenerate and fix AMD and EXT extension html files #290
  • ARM: Update generated HTML for Arm extensions #269
  • EXT: Regenerate and fix AMD and EXT extension html files #290
  • GOOGLE: Regenerate Google extensions using asciidoctor #276
  • HUAWEI: Update generated HTML for huawei extensions #289
  • INTEL: asciidoc fixes for Intel extensions #274
  • KHR: Regenerate KHR extensions using asciidoctor #272
  • NV: Regenerate NV extensions with asciidoctor #275
  • QCOM: the HTML files of the QCOM extensions generated with asciidoctor 2.0.22 #273
• Automatically build HTML specs in CI and publish them via Github Pages Add publishing to pages #297
• Remove HTML files from this repository

No longer doing:

• 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 (Add Github actions workflow to generate and check HTML specs #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 #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.