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.1, follow this guide to get the latest version.
Here are the main breaking changes between the 1.1 and 1.2 versions.
Update the following Python dependencies in docs/pyproject.toml
:
sphinx-scylladb-theme = "~1.2.1" sphinx-multiversion-scylla = "~0.2.11" sphinx-sitemap = "2.2.0"
Edit docs/Makefile
:
Replace:
POETRY = $(HOME)/.local/bin/poetryWith:
POETRY = poetry # Windows variables ifeq ($(OS),Windows_NT) POETRY = $(APPDATA)\Python\Scripts\poetry endif
Add:
# Setup commands .PHONY: setupenv setupenv: pip install -q poetry
Remove the files .github/workflows/docs-*.yml
. Then, copy the new workflows in the .github/workflows
folder. You can download the latest workflows here.
If the default branch is not
master
or the docs are not under thedocs
folder, the workflows to match the project configuration. For example:on: push: branches: - master # edit this line paths: - "docs/**" # edit this line
Commit and push the changes to GitHub (default branch).
To check if the upgrade completed successfully, run the command make preview. Then, check if the site footer displays version 1.2 or greater.
To list versions as unstable:
Define in your conf.py
the list UNSTABLE_VERSIONS
:
# Set which versions are not released yet. UNSTABLE_VERSIONS = ["master"]
Add a new option versions_unstable
in html_options
:
html_theme_options = { "versions_unstable": UNSTABLE_VERSIONS, ... }
Sitemaps are useful for search engines to index content. The toolchain now automatically generates a sitemap for the site.
To install the sitemap extension, list it the conf.py
file:
extensions = [ ..., "sphinx_sitemap", ]
If the project has the multiversion extension enabled, add the following line at the end of the file:
sitemap_url_scheme = "stable/{link}"
If your project uses the Custom landing page feature, add the following lines at the top of the file docs/source/index.rst
:
:hide-sidebar: :hide-secondary-sidebar:
Was this page helpful?