This guide explains how to upgrade the version of the Scylla Sphinx Theme.
The theme version is displayed in the footer of the project’s documentation site.
If your project theme’s version is >=1.2, follow this guide to get the latest version.
Here are the main breaking changes between the 1.2 and 1.3 versions.
Update the following Python dependencies in
sphinx-scylladb-theme = "~1.3.0" redirects_cli ="0.1.1"
Add the new redirects command in
.PHONY: redirects redirects: setup $(POETRY) run redirects-cli fromfile --yaml-file ./_utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
Create a new file
docs/_utils/redirects.yml. If the project has a file
docs/_utils/redirections.yml, rename it to
docs/_utils/redirects.yml and update it to the new format:
Before, redirects were created for all versions:test-redirect: /stable/index
If the project were building docs for the branches
branch-1.0, it would generate the following redirections:
Now, you have more control to define redirects per version. To create the same redirects as in the previous example, the new format is:/stable/test-redirect.html: /stable/index.html /branch-1.0/test-redirect.html: /stable/index.html
Notice that now you must append the
.htmlextension to the redirects.
Remove the file
.github/workflows/docs-pages.yml. Then, copy the new workflow in the
.github/workflows folder. You can download the latest docs-pages.yml workflow 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.3 or greater.
If the project is deploying docs pull request previews with AWS Ampify, you can update the configuration to improve the build time: