# Upgrading from 1.9 to 1.10

This guide explains how to upgrade the ScyllaDB Sphinx Theme from 1.9.x to 1.10.0.

## How to check your current theme version

The theme version is displayed in the footer of the project’s documentation site.

![image](upgrade/version.png)

## What’s new in 1.10

See the [CHANGELOG](https://sphinx-theme.scylladb.com/stable/upgrade/CHANGELOG.md) for the full list of changes in this
release.

## Upgrade to version 1.10

1. Use **Python 3.12 or later** locally and in your documentation build workflows.
2. Update these values in `docs/pyproject.toml` (or the root `pyproject.toml` if it manages your docs). Keep your other dependencies:
   ```toml
   [project]
   requires-python = ">=3.12"
   dependencies = [
       "sphinx-scylladb-theme>=1.10.0,<1.11",
       "sphinx>=9.1.1,<10",
       "sphinx-multiversion-scylla>=0.3.9",
       # Keep your other dependencies here.
   ]
   ```

   Remove any `docutils<0.22` pin. The theme now requires `sphinx-tabs>=3.5.0`, which supports docutils 0.22.
3. From the directory containing that file, update the lockfile:
   ```console
   uv lock --upgrade-package sphinx-scylladb-theme --upgrade-package sphinx==9.1.1 --upgrade-package docutils --upgrade-package sphinx-multiversion-scylla
   uv sync
   ```
4. Add the redirect check to `docs/Makefile`:
   ```makefile
   .PHONY: check-redirects
   check-redirects: setup
   	$(UV) run scylla-check-redirects --yaml _utils/redirects.yaml --conf $(SOURCEDIR)
   ```

   The recipe line must start with a tab.
   Adjust the redirects file path and source directory for your project.
5. Copy these workflows into your repository’s `.github/workflows/` directory:
   - Replace [docs-pr.yaml](https://github.com/scylladb/sphinx-scylladb-theme/blob/1.10.0/.github/workflows/docs-pr.yaml).
   - Add [docs-pr-report.yaml](https://github.com/scylladb/sphinx-scylladb-theme/blob/1.10.0/.github/workflows/docs-pr-report.yaml).

   Adjust the default branch and docs paths, preserving project-specific build steps.

   Keep the filename `docs-pr.yaml`.
   Both workflows must be on the default branch for PR build reports to run.
6. Build and preview the docs, then commit the changes including `uv.lock`:
   ```console
   make -C docs test
   make -C docs preview
   ```

   For multiversion sites, also run `make -C docs multiversion`.

## Per-page update dates

“Last updated” now uses each page’s Git history.
Set `fetch-depth: 0` in checkout steps and check that `html_theme_options["conf_py_path"]` points
to your docs source directory.

## Weekly dependency updates (optional)

1. Copy [docs-dependencies.yaml](https://github.com/scylladb/sphinx-scylladb-theme/blob/1.10.0/.github/workflows/docs-dependencies.yaml)
   into `.github/workflows/` and adjust the Python version and docs paths.
2. Enable **Allow GitHub Actions to create and approve pull requests** in the repository’s Actions settings.

The workflow runs `make -C docs update` and `make -C docs test`, then opens a weekly PR with the updated lockfile.