Was this page helpful?
Caution
You're viewing documentation for a previous version of ScyllaDB Sphinx Theme. Switch to the latest stable version.
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.0, follow this guide to get the latest version.
Here are the main breaking changes between the 0.x and 1.0 versions.
Set sphinx-scylladb-theme
in docs/pyproject.toml
to sphinx-scylladb-theme = "~1.0.0"
.
Edit conf.py
:
Note
Depending on your project configuration, you may find
conf.py
underdocs/source/conf.py
ordocs/conf.py
.
Remove the option
header_links
fromhtml_theme_options
.If exists, remove the option
show_sidebar_index
fromhtml_theme_options
. If this option was set totrue
, set"hide_sidebar_index": "false"
.If they exist, remove or comment out the following lines:
# Add ExpertRec Search # html_js_files = ['expertrec.js']
Edit docs/Makefile
:
Under the section
# Internal variables
, add the following line after the variableALLSPHINXOPTS
:TESTSPHINXOPTS = $(ALLSPHINXOPTS) -W --keep-goingAdd 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 Scylla 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.
Set "hide_sidebar_index": "false"
in html_theme_options
(conf.py
).
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.
Was this page helpful?