Improve docs authoring experience

[fhennig]

As a dev, writing docs is made unpleasant by a few things in the process, especially when writing docs for an Operator, because multiple repos are involved.

Currently the workflow is:

• checkout both the docs repo and the operator repo
• edit the playbook file to point to the local operator repo checkout
• write the docs in the operator repo and rebuild the docs periodically

Main pain points are:

• the setup is cumbersome
• build times are long

Tasks

Preview Give feedback

1. Cache UI bundle in the build
2. investigate Atlas/partial build extension

Links:

• Antora Atlas extension: https://gitlab.com/antora/antora-atlas-extension
• partial build extension: https://github.com/spring-io/antora-extensions#partial-build (depends on the Atlas extension)

[nightkr]

A few things worth exploring IMO:

• For DX, can we have a script for "do a build centered around this branch" that you'd run in your operator repo?
• For build perf, can we try isolating the changes that you're actually concerned about? Either waaaay heavier caching in some form, or maybe we can have a link map of some form for links that should be valid even if they're currently not?

[fhennig]

I like these ideas. There needs to be definitely something so you can preview the docs in the operator repo in isolation with less work.

While looking into this I found this repo: https://github.com/spring-io/antora-extensions with some Antora extensions, there is one called "partial build" which might be helpful for us.

Another low hanging fruit is to not build the UI bundle on every build. especially If we want to have dedicated builds in the operators it might be nice to serve the UI bundle at a URL.

[nightkr]

I'd rather not go back to the served bundle. That was a disaster in terms of both reproducibility and reliability (--fetch is already more than bad enough).

That said, we should definitely cache it to avoid redundant rebuilds...

[nightkr]

Partial/Atlas definitely looks like a good point to start looking from, yes..

[fhennig]

Update: I tried the atlas extension: #574

it works, but I couldn't get partial builds to work.

I asked on the Antora Zulip chat, but didn't get a reply.