Render documentation for GitHub Pages

[peterbrightwell]

Addresses #364

The .github/workflow/docs.yml action renders a site with Zensical, checks for broken links with Lychee and uploads to GitHub pages.

It needs to be run from main to use GitHub Pages, which will need enabling in settings once the PR is merged (default name will be dmf-mxl.github.io/mxl). So to look at it before that see https://peterbrightwell.github.io/mxl -- it's improved a little from what I showed at the TSC, and now adds v1.0 or v1.1 to the sidebar selector (only placeholder v1.1 content for now).

For now the navigation is manually defined in the nav object of zensical.toml (which annoyingly can't be in the docs/ folder -- see zensical/backlog#101) but that can probably be improved later.

For now I have removed the MXL logo from the header as it needs to be in the documentation tree rather than use from mxl-logos, but we can fix this at some point.

[peterbrightwell]

Following discussion on TSC it would be good to get a version selector included. See https://peterbrightwell.github.io/mxl/ for an example of this, allowing you to select between v0.1.0 (stable) and v0.1.1 (latest). (The two trees are the same apart from the comment about versions). This example uses mike with zensical, pending a zensical-native versioning system. It seems to work ok, but unlike the approach in this draft PR, it works by building a tree in the gh-pages branch (see here) and using the "Classic Pages experience" setting rather than a custom GitHub action. A bit more work will be needed turning this example into a usable automation, but it looks promising.

[vt-tv]

Would it be possible to avoid hardcoding absolute urls in the markdown files?

[vt-tv]

Does this mean that we will have to edit the URLs for each branches? (/mxl/blob/main) Can't we use relative URLs so we don't have to change them all the time?

[peterbrightwell]

@vt-tv Unfortunately that requested change won't work as is, as ../.devcontainer/Dockerfile isn't in the docs/ directory, so won't be rendered. So I used the absolute URL to get things going.

We could have a more complete solution by running a pre-build script and use a variable, e.g.

[Dockerfile](https://github.com/{{ repo }}/blob/{{ branch }}/.devcontainer/Dockerfile)

But that's a bit of a pain for authoring and difficulties arise if we want the links to work both on the github.com repo site and the github.io documentation site. For the https://specs.amwa.tv/ NMOS rendering we have some complex scripts to rewrite links (and fix various other issues with the rendering tools), but it's all quite obscure and I certainly wouldn't want to repeat that for MXL.

Probably worth a discussion of what we really want here.

[peterbrightwell]

Or the script could copy across the non-docs part of the repo, including that Dockerfile, include files etc, which might form part of the "documentation". This is something we do for NMOS also, copying APIs/, APIs/schemas/ and examples/ into the render tree.