Build multi version docs in isolated uv environments#483
Conversation
✅ Deploy Preview for jumpstarter-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
WalkthroughThis update removes the use of the Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Makefile
participant multiversion.sh
participant Git
participant Sphinx
participant Versjon
User->>Makefile: make multiversion
Makefile->>multiversion.sh: Execute script
multiversion.sh->>Git: Create worktree for branch
multiversion.sh->>Sphinx: Build docs for branch
Sphinx-->>multiversion.sh: HTML output
multiversion.sh->>Git: Remove worktree
multiversion.sh->>Versjon: Generate version index
multiversion.sh-->>Makefile: Complete
Possibly related PRs
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (6)
💤 Files with no reviewable changes (3)
✅ Files skipped from review due to trivial changes (3)
✨ Finishing Touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/multiversion.sh (2)
21-24: Copy and cleanup per-branch output
Recursivecpandgit worktree removeare appropriate here. Optionally,rsync -acould offer finer control over file attributes and partial updates.
26-28: Generate version index usingversjon
Runninguvx versjonin the output directory is a neat way to build the version index. For reproducibility, you might pin theversjontool version or commit hash.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
uv.lockis excluded by!**/*.lock
📒 Files selected for processing (6)
.gitignore(1 hunks)docs/Makefile(1 hunks)docs/multiversion.sh(1 hunks)docs/source/_templates/sidebar/versions.html(0 hunks)docs/source/conf.py(0 hunks)pyproject.toml(0 hunks)
💤 Files with no reviewable changes (3)
- pyproject.toml
- docs/source/_templates/sidebar/versions.html
- docs/source/conf.py
🧰 Additional context used
🪛 GitHub Actions: documentation
docs/Makefile
[error] 29-29: Git worktree add failed with 'fatal: invalid reference: main'. The branch 'main' does not exist or is not accessible.
[error] 51-51: Make target 'docs-all' failed due to previous error in 'multiversion' target.
⏰ Context from checks skipped due to timeout of 90000ms (11)
- GitHub Check: pytest-matrix (macos-15, 3.12)
- GitHub Check: pytest-matrix (ubuntu-24.04, 3.12)
- GitHub Check: pytest-matrix (ubuntu-24.04, 3.13)
- GitHub Check: pytest-matrix (ubuntu-24.04, 3.11)
- GitHub Check: pytest-matrix (macos-15, 3.13)
- GitHub Check: pytest-matrix (macos-15, 3.11)
- GitHub Check: e2e
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter-utils Dockerfile.utils)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter-devspace .devfile/Containerfile.client)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter-dev .devfile/Containerfile)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter Dockerfile)
🔇 Additional comments (7)
.gitignore (1)
166-166: Skip formatting-only change.
The added trailing newline does not affect any ignore rules or logic.docs/Makefile (2)
28-30: Simplifiedmultiversiontarget usage
Invoking the external scriptmultiversion.shis a clean abstraction over the previous inline commands. Ensure thatdocs/multiversion.shis present and has the executable bit set (chmod +x).🧰 Tools
🪛 GitHub Actions: documentation
[error] 29-29: Git worktree add failed with 'fatal: invalid reference: main'. The branch 'main' does not exist or is not accessible.
33-33: Skip formatting-only change.
The added newline in theserve-multiversiontarget is purely cosmetic.docs/multiversion.sh (4)
1-2: Validate strict mode settings
Using the bash shebang withset -euox pipefailis an excellent practice to catch errors early and improve script robustness.
7-9: Resolve script and output directory paths robustly
CalculatingSCRIPT_DIRand derivingOUTPUT_DIRrelative to the script makes the layout portable and self-contained.
10-12: Ensure clean build directory
Removing and recreating thebuilddirectory at the start guarantees no stale artifacts carry over between runs.
13-20: Loop through branches to build docs
Usinggit worktree add --detachwith a per-branchmake htmland version override is a clear and maintainable approach.
| declare -a BRANCHES=("main" "release-0.5" "release-0.6") | ||
|
|
There was a problem hiding this comment.
Handle default branch detection dynamically
Hardcoding "main" will fail if the repository’s default branch is named differently (e.g., master), as shown by the CI error fatal: invalid reference: main. Consider auto-detecting the default branch:
- declare -a BRANCHES=("main" "release-0.5" "release-0.6")
+ DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD | sed 's|origin/||')
+ declare -a BRANCHES=("$DEFAULT_BRANCH" "release-0.5" "release-0.6")📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| declare -a BRANCHES=("main" "release-0.5" "release-0.6") | |
| # replace the hard-coded “main” with whatever the remote’s HEAD points to | |
| DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD | sed 's|origin/||') | |
| declare -a BRANCHES=("$DEFAULT_BRANCH" "release-0.5" "release-0.6") |
There was a problem hiding this comment.
This script is not generic, just for our repo, the extra complexity is not worth it
There was a problem hiding this comment.
This script is not generic, just for our repo, the extra complexity is not worth it
There was a problem hiding this comment.
@mangelajo I understand your point. Since the script is specific to your repository, keeping it simple without the additional dynamic branch detection makes sense. I'll accept your decision and won't pursue this suggestion further.
✏️ Learnings added
Learnt from: mangelajo
PR: jumpstarter-dev/jumpstarter#483
File: docs/multiversion.sh:4-5
Timestamp: 2025-05-13T18:08:55.245Z
Learning: The script `docs/multiversion.sh` is intentionally repository-specific and not meant to be generic. The hardcoded branches ("main", "release-0.5", "release-0.6") are deliberate, and suggestions to make the script more generic by dynamically detecting branches should be avoided.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
There was a problem hiding this comment.
@mangelajo Understood! You're right that if the script is specific to this repository and not meant to be generic, keeping it simple makes sense. Thanks for the clarification.
✏️ Learnings added
Learnt from: mangelajo
PR: jumpstarter-dev/jumpstarter#483
File: docs/multiversion.sh:4-5
Timestamp: 2025-05-13T18:08:55.371Z
Learning: The multiversion.sh script in the docs directory is intentionally repository-specific with hardcoded branch names (including "main") and doesn't need to handle varying default branch names. Adding complexity for generalization isn't necessary.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
|
|
||
| cp -r "${WORKTREE}/docs/build/html" "${OUTPUT_DIR}/${BRANCH}" | ||
|
|
||
| git worktree remove --force "${WORKTREE}" |
There was a problem hiding this comment.
I didn't know about work tree
|
Backport failed for Please cherry-pick the changes locally and resolve any conflicts. git fetch origin release-0.6
git worktree add -d .worktree/backport-483-to-release-0.6 origin/release-0.6
cd .worktree/backport-483-to-release-0.6
git switch --create backport-483-to-release-0.6
git cherry-pick -x 6e8055fd4064fa581bf4a74e33a8310b9f1877da |
|
Backport failed for Please cherry-pick the changes locally and resolve any conflicts. git fetch origin release-0.6
git worktree add -d .worktree/backport-483-to-release-0.6 origin/release-0.6
cd .worktree/backport-483-to-release-0.6
git switch --create backport-483-to-release-0.6
git cherry-pick -x 6e8055fd4064fa581bf4a74e33a8310b9f1877da |
Backport #483 to release 0.6
Summary by CodeRabbit
New Features
Removals
Chores