Wire up post-0.11.x old docsites into Antora

[lihaoyi]

Fixes #2455

They can now be added to val docTags, and will appear as previous versions on the docsite

To support this mostly transparently, I checkout the relevant versions of com-lihaoyi/mill as part of githubPages and run ./mill to build their docs. This saves us the hassle of storing the materialized .adoc files somewhere and worrying about them getting stale/corrupted/accessible/etc.

The versions listed in docs/antora.yml are incorrect for some of the old tags like 0.11.10. We probably should generate them in build.sc to avoid duplication.

If we intend to support ongoing development of old branches, we probably should use moving 0.11.x branches rather than fixed 0.11.x tags for the doc-site, so that improvements to the documentation would get picked up without additional releases. We might also want to make the latest stable version the default page, so we can merge incremental documentation into main without confusing users. But these improvements can come in follow ups

[lefou]

The versions listed in docs/antora.yml are incorrect for some of the old tags like 0.11.10. We probably should generate them in build.sc to avoid duplication.

This is because these need to be updated before we tag the next release. I always did that when tagging a Mill release.

But as you suggested, we can also open a <version> branches to fix and maintain the documentation for a specific version, if we oversaw something like this. Should be doable on demand. Easier is to just update that file in the "Prepare release <version>" commit, which we could try to pre-generate with Mill. Maybe, a openReleasePullRequest target, that uses gh pr create --draft to interact with Github?

[lefou]

Took me a while to recognize that this change is only visible via docs.githubPages but not docs.localPages. Looks good. IIRC, the main motivation for localPages was, to have the full pages with links that work on the local machine, so that navigating resources and editing as part of proof-reading was easier. In that spirit, we should include these extra versions also in localPages.

[lihaoyi]

@lefou I updated the PR to also replace the versions in antora.yml for old branches too. Now the versions in that file in repo are just a stub, which should get automatically filled in by Mill during the build

[lihaoyi]

btw do you know if there's some way to speedup/cache/parallelize the antora build step? With the addition of graphviz and the duplication due to an old version, generated the pages now takes really long

[lefou]

btw do you know if there's some way to speedup/cache/parallelize the antora build step? With the addition of graphviz and the duplication due to an old version, generated the pages now takes really long

Not yet. Part of the slowdowns is probably because we clean the directory every time. I don't use Antora elsewhere, so I have no idea what build times to expect in general.

A quick search discovered, that there is a Gradle plugin for Antora, which is used by the spring project to render their documentation. We could look how they do it, maybe port it over.

[lefou]

https://antora.zulipchat.com/#narrow/stream/282400-users/topic/build.20site.20locally.20very.20slow