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.0, follow this guide to get the latest version.
Here are the main breaking changes between the 1.0 and 1.1 versions.
Install Poetry 1.12 or later on your computer.
Update the following Python dependencies in
[tool.poetry.dependencies] python = "^3.7" pyyaml = "^6.0" pygments = "^2.11.2" recommonmark = "^0.7.1" sphinx-scylladb-theme = "~1.1.0" sphinx-sitemap = "^2.1.0" sphinx-autobuild = "^2021.3.14" Sphinx = "^4.3.2" sphinx-multiversion-scylla = "~0.2.10"
conf.py, remove the option
"hide_sidebar_index": "true" (if exists).
Depending on your project configuration, you may find
Replace:POETRY = $(HOME)/.poetry/bin/poetry
With:POETRY = $(HOME)/.local/bin/poetry
Replace:.PHONY: setup setup: ./_utils/setup.sh
With:.PHONY: setup setup: $(POETRY) install $(POETRY) update
Remove the file
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
masteror the docs are not under the
docsfolder, 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.1 or greater.
If you were using the Custom landing page feature:
Add the following lines at the top of the file
:full-width: :hide-version-warning: :hide-pre-content: :hide-post-content: :landing:
Remove the lines:
.. raw:: html <div class="landing landing--floating">
Remember to delete its closing
</div>tag. Here is the complete diff.