Skip to content

docs: add versioned docs - #378

Open
awphi wants to merge 6 commits into
mainfrom
bump-arm-docs
Open

docs: add versioned docs#378
awphi wants to merge 6 commits into
mainfrom
bump-arm-docs

Conversation

@awphi

@awphi awphi commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Changes

  • Bumps us to the latest version of ADP; 0.6.0 which comes with
    • New styling
    • Support for versioned docs
  • Adds automated versioned docs releasing:
    • The main pain point of the docs versioning is it requires hard-coding a list of refs we want to host docs for in the repo. This felt like a lot of manual work so this adds a little script to generate the relevant config for the last 5 major releases.
    • Runs said script prior to publishing to staging. As part of this, the script also supports passing --include-head so we can preview a 'Latest' version in staging
    • Adds a compose.preview.yaml compose project to preview the production/staging version of the docs locally. I don't foresee this being desperately useful but it does provide some level of confidence before deploying.

I'm keen for feedback if we think the automated versions generation is the right way to go + if we need the local production preview project at all. Lmk!

Checklist

  • 🤖 This change is covered by tests as required.
  • 🤹 All required manual testing has been performed.
  • 📖 All documentation updates are complete.

awphi added 4 commits July 27, 2026 15:27
Signed-off-by: awphi <26072111+awphi@users.noreply.github.com>
Signed-off-by: awphi <26072111+awphi@users.noreply.github.com>
Signed-off-by: awphi <26072111+awphi@users.noreply.github.com>
Signed-off-by: awphi <26072111+awphi@users.noreply.github.com>
@awphi
awphi requested a review from a team as a code owner July 28, 2026 10:32

@muchzill4 muchzill4 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to push latest major, not major.0.0. I.e.: 7.5.2 > 7.0.0.

Comment thread docs/scripts/generate-docs-config.sh Outdated

release_refs=$(
for ref in $(gh release list --exclude-drafts --exclude-pre-releases --limit 1000 --json tagName --jq '[.[] | select(.tagName | test("^v?[0-9]+\\.0\\.0$"))][:5][].tagName'); do
if git cat-file -e "$ref:docs/docs-config.json" 2>/dev/null; then

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

has_docs_config_at_ref() {
  git cat-file -e "$1:docs/docs-config.json" 2>/dev/null
}

And maybe:

last_five_major_release_tags=$(
  gh release list \
    --exclude-drafts --exclude-pre-releases \
    --limit 1000 --json tagName |
    jq '[.[] | select(.tagName | test("^v?[0-9]+\\.0\\.0$"))][:5][].tagName'
)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed, have hard-coded a minimum major version to search from + made it fetch all latest releases from each major prefix

awphi added 2 commits July 28, 2026 14:56
Signed-off-by: awphi <26072111+awphi@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants