jchong9 opened a new pull request, #489:
URL: https://github.com/apache/superset-kubernetes-operator/pull/489
## Summary
<!--
Required. A paragraph explaining what this PR does and why. A reviewer should
understand the motivation and scope from this section alone, without reading
the diff.
-->
Adds versioned documentation publishing so readers can browse the current
unreleased docs, the latest release, or prior minor releases. The docs workflow
builds and publishes the appropriate documentation slices and maintains the
version manifest (`versions.json`) and switcher.
## Details
<!--
Optional. Implementation notes, design decisions, or a bullet list of
individual
changes for smaller PRs. For larger PRs, use a structured summary covering
the
key decisions and their rationale. Delete this section if the summary is
sufficient.
-->
The docs workflow validates pull requests, publishes `main` and the
site-root pages on branch updates, publishes a minor-version snapshot on final
release tags, and supports dry-run or deployed backfills for historical tags.
```mermaid
flowchart LR
A[Docs workflow starts] --> B[Resolve ref and target]
B --> C[Test docs and prepare links]
C --> D[Build with Zensical --strict]
D --> E[Assemble root and versioned site]
E --> F{PR, dry run, or deploy?}
F -->|PR| G[Validate only]
F -->|Dry run| H[Show gh-pages diff]
F -->|Push or tag| I[Deploy to gh-pages]
```
Before building, CI rewrites relative Markdown links in its checkout:
- Links from versioned pages to shared, unversioned pages become absolute
links to the shared page at the site root.
- Links from shared pages to versioned pages point to the appropriate
version path (for example, `/latest/`).
The Markdown files in the repository remain unchanged. This approach was
chosen because:
1. **Smaller, focused PRs:** Rewriting links in the actual docs would touch
many content files and add unrelated link churn to future documentation changes.
2. **Less maintenance:** Authors can use ordinary relative Markdown links
without managing separate links for each published version or deployment URL.
Historical releases also pass through link preparation when backfilled.
3. **Less invasive future migration:** If Zensical adds native versioning,
this approach keeps the change localized to CI rather than requiring edits
across the docs. Older published releases may need link migration if the URL
layout changes, so limiting the current change makes that work smaller.
The scripts use Python for structured version-manifest JSON handling, input
validation, and redirect-page generation; the shell scripts orchestrate GitHub
Actions, Zensical builds, and site assembly.
The version switcher stores the selected version for the user. Without that
preference, navigating from a selected release to an unversioned page and then
back to versioned documentation would send the user to `latest/`, losing their
selection and interrupting their navigation flow.
The workflow logic is in `scripts/run-docs-ci.sh` to avoid duplicating
event/ref selection, link preparation, and build commands in `docs.yml`. Both
the build and deploy jobs need to assemble docs, and the same helper keeps
those paths consistent.
<details>
<summary>Testing</summary>
### Build and deployment checks
- [x] `zensical build --strict` passes.
- [x] Regular branch deployment succeeds.
- [x] Tested on [my
fork](https://github.com/jchong9/superset-kubernetes-operator/actions/workflows/docs.yml)
by updating `site_url` and the docs workflow branch, then running branch
deployments and a `workflow_dispatch` backfill.
- [x] Manually checked deployed pages and links to confirm they resolve to
the expected fork and documentation versions.
### Versioning and backfill scenarios
- [x] Publishing a new minor version moves the `latest` alias to that
version.
- [x] Publishing an older patch for an already-published minor fails by
default.
- [ ] A manual backfill with `force` enabled allows replacing that minor's
docs with the older patch.
- [x] A non-existent release tag fails.
- [x] Random text supplied as the workflow-dispatch ref fails validation.
- [x] Multiple minor versions appear in the version switcher.
</details>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
