Use polyversion + uv to build docs - #308
Merged
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #308 +/- ##
=======================================
Coverage 89.00% 89.00%
=======================================
Files 58 58
Lines 2847 2847
Branches 507 507
=======================================
Hits 2534 2534
Misses 210 210
Partials 103 103
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR migrates the documentation build system from sphinx-multiversion to sphinx-polyversion, and updates CI to use uv for dependency provisioning while adding version selectors/banners across built doc versions.
Changes:
- Switch docs versioning/build to
sphinx-polyversion(newdocs/poly.py, updated Makefile). - Update packaging metadata and lockfile for the new docs build approach (extras reshuffle,
uvsource forsphinx-polyversion, Python >=3.12). - Update docs UI assets/templates to inject a version selector + version banners into built HTML, and update GitHub Actions to build with
uv.
Reviewed changes
Copilot reviewed 13 out of 14 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
uv.lock |
Updates the locked environment for Python 3.12+ and new docs/tooling deps (incl. sphinx-polyversion). |
pyproject.toml |
Restructures extras (introduces sphinx extra), adds tool.uv.sources override for sphinx-polyversion. |
docs/poly.py |
New sphinx-polyversion driver configuration + post-build HTML patching for selectors/banners. |
docs/poly_files/templates/index.html |
Adds root redirect template for “latest version”. |
docs/poly_files/patches/versions.html |
Adds patched Furo-style version selector list for built docs. |
docs/poly_files/patches/versions_rtd.html |
Adds RTD-theme-compatible versions selector patch for older docs. |
docs/poly_files/patches/version_banner.html |
Adds per-version banner (latest/old/dev) for Furo-based docs. |
docs/poly_files/patches/version_banner_rtd.html |
Adds “old version” banner for RTD-themed docs. |
docs/Makefile |
Updates targets to use sphinx-build locally and sphinx-polyversion for multi-version builds. |
docs/conf.py |
Integrates sphinx-polyversion context loading and adds version selector CSS. |
docs/_templates/versions.html |
Replaces old RTD versions block with a Furo-native placeholder for later patching. |
docs/_static/css/version_selector.css |
Adds styling for the new selector + version banners. |
.github/workflows/docs.yml |
Switches docs build workflow to uv sync and sphinx-polyversion build path. |
.github/workflows/docs-preview.yml |
Switches preview workflow to uv, updates build output path for PR previews. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+37
to
+41
| tag_revisions = [ | ||
| rev | ||
| for rev in html_context["revisions"] | ||
| if rev.type_ == GitRefType.TAG and rev.name.startswith("v") | ||
| ] |
Comment on lines
+279
to
+281
| sorted_tags = sorted( | ||
| [ref for ref in refs if ref.type_ == GitRefType.TAG], key=lambda x: x.name | ||
| ) |
Comment on lines
+308
to
+310
| TAG_REGEX = ( | ||
| "|".join(to_build) if to_build else r"^$" | ||
| ) # match nothing if empty |
Comment on lines
+542
to
+548
| [ | ||
| tag | ||
| for tag in built_versions["tags"] | ||
| if tag.name == built_dir.name | ||
| ] | ||
| ) | ||
| if int(built_dir.name.split(".")[1]) < 3: |
Comment on lines
+6
to
+10
| <meta | ||
| http-equiv="refresh" | ||
| content="0; url=./{{ latest.name }}/index.html" | ||
| /> | ||
| <link rel="canonical" href="./{{ latest.name }}/index.html" /> |
| {%- elif status == "old" %} | ||
| <strong>⚠ Old version</strong> — You are viewing an old version of julearn | ||
| ({{ current_version.name }}). Switch to the | ||
| <a href="{VERSIONROOT}{{ latest.name }}/index.html">latest stable release ({{ latest.name }})</a>. |
| <strong>🚧 Development version</strong> — You are viewing the development (unstable) | ||
| version of julearn. This may contain unreleased features or breaking changes. | ||
| For the latest stable release, see | ||
| <a href="{VERSIONROOT}{{ latest.name }}/index.html">{{ latest.name }}</a>. |
| <div role="note" style="padding:0.75rem 1rem;margin-bottom:1.5rem;background-color:#f8d7da;border-left:4px solid #dc3545;font-size:0.9em;line-height:1.5;"> | ||
| <strong>⚠ Old version</strong> — You are viewing an old version of julearn | ||
| ({{ current_version.name }}). Switch to the | ||
| <a href="{VERSIONROOT}{{ latest.name }}/index.html">latest stable release ({{ latest.name }})</a>. |
|
|
||
| clean: | ||
| rm -rf $(BUILDDIR)/* | ||
| rm -rf $(BUILDDIR)/main |
| rm -rf api/generated/ | ||
|
|
||
| cleanall: clean | ||
| rm -rf $(BUILDDIR)/* |
|
Contributor
Author
|
@synchon Once we merge this PR, I will pull the gh-pages and re-build the entire documentation locally. Then the CI will take over. |
synchon
approved these changes
May 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR changes the way we are currently building docs