feat(docs): implement documentation versioning#469
Conversation
closes #179 Signed-off-by: Luka Peschke <luka.peschke@toucantoco.com>
lukapeschke
added
documentation
There was a problem hiding this comment.
Pull request overview
Implements versioned documentation builds (à la ReadTheDocs) so users can browse docs per release tag and switch versions from within the generated pdoc pages.
Changes:
- Add a script to maintain
docs/versions.jsonand generate a redirectingdocs/index.html. - Update Makefile targets to build
latestdocs and versioned docs using a custom pdoc template. - Update the docs GitHub Actions workflow to build on
main, tags, and manual dispatch, and publish versioned artifacts togh-pages.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
scripts/update_versions.py |
New helper to update versions.json and generate the redirect page used as the docs entrypoint. |
Makefile |
Builds docs into docs/latest and adds a doc-versioned target for CI/tag builds. |
doc-templates/module.html.jinja2 |
Adds a client-side version switcher that reads versions.json and rewrites the current page URL across versions. |
.github/workflows/docs.yml |
Builds docs on main/tags/dispatch and deploys per-version outputs to gh-pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then | ||
| echo "version=${{ github.event.inputs.version_tag }}" >> "$GITHUB_OUTPUT" | ||
| echo "is_stable=true" >> "$GITHUB_OUTPUT" | ||
| elif [[ "${GITHUB_REF}" == refs/tags/v* ]]; then | ||
| echo "version=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT" | ||
| echo "is_stable=true" >> "$GITHUB_OUTPUT" |
There was a problem hiding this comment.
The workflow currently sets is_stable=true for any tag build and for all workflow_dispatch runs. That means building docs for an older tag (or manually dispatching a build for an older version) will flip the “stable” redirect and version label to that older version. Consider making “mark as stable” an explicit workflow_dispatch input (default false) and/or only setting --stable when the tag is the highest semver release (or when the release is published).
| cargo doc --no-deps --lib -p fastexcel --features polars | ||
|
|
||
| .PHONY: doc-versioned ## Build versioned documentation (CI usage: VERSION=v0.19.0 make doc-versioned) | ||
| doc-versioned: build-dev |
There was a problem hiding this comment.
doc-versioned relies on $(VERSION) but doesn’t fail fast when it’s unset. Running make doc-versioned without VERSION=... will write to docs/ and add an entry with an empty path to versions.json. Add a guard (e.g., ifndef VERSION -> error) or provide a sensible default.
| doc-versioned: build-dev | |
| doc-versioned: build-dev | |
| @if [ -z "$(VERSION)" ]; then \ | |
| echo "ERROR: VERSION is not set. Usage: VERSION=v0.19.0 make doc-versioned"; \ | |
| exit 1; \ | |
| fi |
| var idx = window.location.pathname.indexOf(currentVersion); | ||
| var baseUrl = window.location.pathname.substring(0, idx); | ||
| // Get the page path after the version segment | ||
| var pagePath = window.location.pathname.substring(idx + currentVersion.length); | ||
|
|
There was a problem hiding this comment.
The computed pagePath only uses window.location.pathname, so switching versions drops the current query string and hash (anchor), which is especially noticeable when linking to sections within the docs. Consider including window.location.search and window.location.hash when constructing the target URL so navigation preserves anchors.
| <head> | ||
| <meta charset="utf-8"> | ||
| <meta http-equiv="refresh" content="0; url=./{redirect_path}/fastexcel.html"/> | ||
| </head> | ||
| <body> |
There was a problem hiding this comment.
redirect_path is interpolated directly into generated HTML attributes (meta refresh and <a href=...>). Since --version can come from a workflow_dispatch input, a malformed value can break the redirect page (and potentially inject markup). Consider validating version/redirect_path against an allowlist like latest or ^v\d+(\.\d+)*$ before writing index.html, and erroring out with a clear message if it doesn’t match.
Signed-off-by: Luka Peschke <luka.peschke@toucantoco.com>
|
@PrettyWood could you please have a second look ? |
closes #179