Repository navigation
Improve docs authoring experience #519
Description
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
- [ ] Cache UI bundle in the build
- [ ] 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)
Activity
nightkr commentedon Jan 8, 2024
A few things worth exploring IMO:
fhennig commentedon Jan 8, 2024
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 commentedon Jan 8, 2024
I'd rather not go back to the served bundle. That was a disaster in terms of both reproducibility and reliability (
--fetchis already more than bad enough).That said, we should definitely cache it to avoid redundant rebuilds...
nightkr commentedon Jan 8, 2024
Partial/Atlas definitely looks like a good point to start looking from, yes..
fhennig commentedon Apr 2, 2024
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.