chore: Upgrade theme to 1.9: Sphinx 9, uv, Python 3.11+, Node 22

This release upgrades the core toolchain: Sphinx 9.x, myst-parser 5.x, Python 3.11+, Node.js 22, and replaces Poetry with uv for dependency management.

The bundled sphinx-multiversion extension has been updated for Sphinx 9 compatibility.

1. Install uv first:

make setupenv

2. Then set up the environment and build the docs:

make setup
make preview

We'll help projects migrate from 1.8 to 1.9. See the upgrade guide for step-by-step instructions.

Author: dgarcia360

.github/dependabot.yaml

@@ -14,13 +14,13 @@ updates:
     schedule:
       interval: "daily"
 
-  # Maintain dependencies for Poetry
-  - package-ecosystem: "pip"
+  # Maintain dependencies for uv
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
       interval: "daily"
 
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/docs/_utils"
     schedule:
       interval: "daily"

.github/workflows/docs-pages.yaml

@@ -21,10 +21,14 @@ jobs:
           ref: ${{ github.event.repository.default_branch }}
           persist-credentials: false
           fetch-depth: 0
+
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.10'
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
 
       - name: Set up env
         run: make -C docs setupenv

.github/workflows/docs-pr.yaml

@@ -22,7 +22,10 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.10'
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
 
       - name: Set up env
         run: make -C docs setupenv

.github/workflows/frontend-tests.yaml

@@ -0,0 +1,45 @@
+name: "Theme / Frontend build"
+
+on:
+  pull_request:
+    branches:
+      - master
+    paths:
+      - "src/**"
+      - "config/**"
+      - "package.json"
+      - "package-lock.json"
+  push:
+    branches:
+      - master
+    paths:
+      - "src/**"
+      - "config/**"
+      - "package.json"
+      - "package-lock.json"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Set up Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build frontend
+        run: npm run build

.github/workflows/multiversion-tests.yaml

@@ -28,7 +28,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.10'
+          python-version: '3.12'
 
       - name: Set up requirements
         run: python -m pip install -r requirements.txt

.github/workflows/theme-tests.yaml

@@ -15,22 +15,29 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
     steps:
       - name: Checkout
         uses: actions/checkout@v6
         with:
           persist-credentials: false
           fetch-depth: 0
 
-      - name: Set up Python
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
-          python-version: "3.10"
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
 
       - name: Set up env
         run: |
           make -C docs setupenv
-          poetry install
+          uv sync
 
       - name: Run tests
-        run: poetry run pytest .
+        run: uv run pytest .

deploy.sh

@@ -17,9 +17,9 @@ if git checkout master &&
     [ `git rev-list HEAD...origin/master --count` == 0 ] &&
     git merge origin/master
 then
-    poetry version patch
-    poetry build
-    poetry publish
+    uv version --bump patch
+    uv build
+    uv publish
 else
     echo "Error: Your local repository has some changes not pushed or"\
          "someone has updated the repository while you where editing code."\

docs/Makefile

@@ -1,8 +1,8 @@
 # Global variables
 # You can set these variables from the command line.
-POETRY        = poetry
+UV            = uv
 SPHINXOPTS    = -j auto
-SPHINXBUILD   = $(POETRY) run sphinx-build
+SPHINXBUILD   = $(UV) run sphinx-build
 PAPER         =
 BUILDDIR      = _build
 SOURCEDIR     = source
@@ -19,15 +19,15 @@ all: dirhtml
 # Setup commands
 .PHONY: setupenv
 setupenv:
-	pip install -q poetry
+	pip install -q uv
 
 .PHONY: setup
 setup:
-	$(POETRY) install
+	$(UV) sync
 
 .PHONY: update
 update:
-	$(POETRY) update
+	$(UV) sync --upgrade
 
 # Clean commands
 .PHONY: pristine
@@ -65,24 +65,24 @@ epub3: setup
 
 .PHONY: multiversion
 multiversion: setup
-	$(POETRY) run sphinx-multiversion source $(BUILDDIR)/dirhtml
+	$(UV) run sphinx-multiversion source $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: redirects
 redirects: setup
-	$(POETRY) run redirects-cli fromfile --yaml-file _utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml
+	$(UV) run redirects-cli fromfile --yaml-file _utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 # Preview commands
 .PHONY: preview
 preview: setup
-	$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
+	$(UV) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
 
 .PHONY: multiversionpreview
 multiversionpreview: multiversion
-	$(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
+	$(UV) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
 
 # Test commands
 .PHONY: test

docs/_utils/dependabot_template.yml

@@ -1,6 +1,6 @@
 version: 2
 updates:
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/docs"
     schedule:
       interval: "daily"

docs/_utils/pyproject_template.toml

@@ -1,21 +1,18 @@
-[tool.poetry]
+[project]
 name = "sphinx-docs"
 description = "ScyllaDB Documentation"
 version = "0.1.0"
-authors = ["ScyllaDB Documentation Contributors"]
-package-mode = false
+requires-python = ">=3.11"
+dependencies = [
+    "pygments>=2.18.0",
+    "sphinx-scylladb-theme>=1.9.0",
+    "myst-parser>=5.0.0",
+    "sphinx-autobuild>=2025.08.25",
+    "sphinx>=9.0",
+    "sphinx-multiversion-scylla>=0.3.1",
+    "sphinx-sitemap>=2.9.0",
+    "redirects_cli>=0.1.3",
+]
 
-[tool.poetry.dependencies]
-python = "^3.10"
-pygments = "^2.18.0"
-sphinx-scylladb-theme = "^1.8.1"
-myst-parser = "^3.0.1"
-sphinx-autobuild = "^2024.4.19"
-Sphinx = "^7.3.7"
-sphinx-multiversion-scylla = "^0.3.1"
-sphinx-sitemap = "^2.6.0"
-redirects_cli ="^0.1.3"
-
-[build-system]
-requires = ["poetry>=1.8.0"]
-build-backend = "poetry.masonry.api"
+[tool.uv]
+package = false