Upgrading from 1.9 to 1.10¶

How to check your current theme version¶

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

What’s new in 1.10¶

See the CHANGELOG 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:

   [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:

   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:

   .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.

   • Add 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:

   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 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.