Was this page helpful?
Caution
You're viewing documentation for an unstable version of ScyllaDB Sphinx Theme. Switch to the latest stable version.
This guide explains how to upgrade the version of the ScyllaDB Sphinx Theme.
The theme version is displayed in the footer of the project’s documentation site.
If your project theme’s version is >=1.7, follow this guide to get the latest version.
Here are the main breaking changes between the 1.6 and 1.7 versions.
We recommend that teams commit the poetry.lock
file to the repository.
Doing so ensures that dependencies are locked, leading to consistent documentation builds across different environments.
For more information, see Committing your poetry.lock file to version control.
Steps to apply this change:
Remove the poetry.lock
file from the .gitignore
file. This file could be either in the root of the repository or in the docs
directory.
Update the docs/Makefile
and remove the rm -f poetry.lock
command from the clean
command:
# Clean commands .PHONY: clean clean: rm -rf $(BUILDDIR)/* # rm -f poetry.lock
In the same file, remove the line $(POETRY) update
from the setup
command:
.PHONY: setup setup: $(POETRY) install # $(POETRY) update
In the same file, add a new command to update Python dependencies:
.PHONY: update update: $(POETRY) update
Add the following dependabot.yml
configuration file in the .github
directory:
version: 2 updates: - package-ecosystem: "pip" directory: "/docs" schedule: interval: "daily" allow: - dependency-name: "sphinx-scylladb-theme" - dependency-name: "sphinx-multiversion-scylla"
This configuration helps keep your project up-to-date with the latest theme versions automatically.
In the docs/pyproject.toml
file, set Poetry to use the non-package mode:
[tool.poetry] name = "scylla" description = "Scylla Documentation" version = "4.3.0" authors = ["ScyllaDB Contributors"] package-mode = false
Ensure all dependencies in the docs/pyproject.toml
file are configured to install the latest minor versions by using the ^
symbol followed by the major and minor version number:
Example:
(...) [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" (...)
In the same docs/pyproject.toml
file, update the poetry dependency to version 1.8.0:
(...) [build-system] requires = ["poetry>=1.8.0"] build-backend = "poetry.masonry.api"
Run the following command in the docs``folder to update the ``poetry.lock
file:
poetry lock --no-update
Preview the docs. Ensure sure they render without errors:
make preview
Commit the changes to the repository, including the poetry.lock
file.
If your homepage was using mascots or icons, update them to the new ones.
For more information, see:
Was this page helpful?