Preview build POC (step 1: local)

[osfameron]

Step 1: a command preview to build locally

• run from inside a content repo like docs-columnar
• no need to create a playbook! Just preview
• Will look at antora.yml to add additional repos/overrides
  see e.g. https://github.com/couchbaselabs/docs-columnar/blob/preview-build/antora.yml#L12-L21
• bases the playbook on docs-site/antora-playbook.yml
• and adds overrides from docs-site/antora-playbook.preview.local.yml

SCREENCAST: https://drive.google.com/file/d/1ec4WXk77TYtQcJFjJDWMydf2gyhXLs9p/view?usp=sharing

NB: you'll want to add something like alias preview='node ~/couchbase/docs-site/scripts/preview/preview.js' to your .zshrc (correct the path for your case)

Roadmap:
Step 2: build remotely when branch is pushed
Step 3: niceties for VSCode etc.?

[RayOffiah]

What can I say? This is great!

I can get a local build for one module up and running in a few seconds, as opposed to half an hour!

How does this work?

[osfameron]

How does this work?

It figures out url, branch, start_path from the current directory,
then looks for docs_site to find the template antora-playbook.yml
then munges them all together (plus any config from the antora.yml, and a local.yml override file) to create a temporary playbook.

Happy to talk through it if you want to know the gory details 👍

[mojavelinux]

I just want you to know that this is exactly what the Gradle Antora plugin and Antora Maven plugin were designed to do, without having to mess with JavaScript.

See https://docs.antora.org/gradle-plugin/latest/playbook-provider/ and https://docs.antora.org/maven-plugin/latest/playbook-provider/

The playbook file is managed centrally in any repository you want. It then sets up a playbook to build just the content branch.

Even if you don't end up using Maven or Gradle, you might be able to draw ideas from the design of the playbook provider capability in the plugins.

NOTE: We envision adding this capability to the antora command, but we have not yet had the opportunity to explore it yet.

[osfameron]

Thanks @mojavelinux !
I will have a look - usually a bit wary of adding maven/gradle dependencies (only because I don't understand them and have had bad experience trying to maintain some bitrotted ones) but as you say, lots to learn from them, thanks.

At the very least, it sense-checks the requirement 👍