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 0.x and 1.0 versions.
sphinx-scylladb-theme = "~1.0.0".
Depending on your project configuration, you may find
Remove the option
If exists, remove the option
html_theme_options. If this option was set to
If they exist, remove or comment out the following lines:# Add ExpertRec Search # html_js_files = ['expertrec.js']
Under the section
# Internal variables, add the following line after the variable
ALLSPHINXOPTS:TESTSPHINXOPTS = $(ALLSPHINXOPTS) -W --keep-going
Add the following lines at the end of the
Makefile:.PHONY: test test: setup $(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
Remove the file
.github/workflows/pages.yml. Then, copy the new workflows in the
.github/workflows folder. You can download the latest workflows here.
To check if the upgrade completed successfully, run the command make preview. Then, check if the site footer displays version 1.0 or greater.
With 1.0, you can add a custom landing page for your project using the new topic box components. For example, check out ScyllaDB Sphinx Theme landing page for inspiration.
To add a landing page to your project:
Create a new
docs/source/index.rst file. Here you can find a sample template ready to be adapted.
"hide_sidebar_index": "false" in
If your project is open-source, we invite you to enable the new “Edit on GitHub” option. For more information, see Template Options / Contribute button.