Sphinx ScyllaDB Theme 1.0 is now released 🥳
Learn more

Migrating from 0.x to 1.0

This guide explains how to upgrade the version of the Scylla Sphinx Theme.

How to check your current theme version

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.

Upgrade to version 1.0

Here are the main breaking changes between the 0.x and 1.0 versions.

  1. Set sphinx-scylladb-theme in docs/pyproject.toml to sphinx-scylladb-theme = "~1.0.0".

  2. Edit conf.py:


    Depending on your project configuration, you may find conf.py under docs/source/conf.py or docs/conf.py.

    1. Remove the option header_links from html_theme_options.

    2. If exist, remove the option show_sidebar_index from html_theme_options. If this option was set to true, set "hide_sidebar_index": "false".

    3. If they exist, remove or comment out the following lines:

      # Add ExpertRec Search
      # html_js_files = ['expertrec.js']
  3. Edit docs/Makefile:

    1. Under the section # Internal variables, add the following line after the variable ALLSPHINXOPTS:

      TESTSPHINXOPTS  = $(ALLSPHINXOPTS) -W --keep-going
    2. Add the following lines at the end of the Makefile:

      .PHONY: test
      test: setup
          $(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
          @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
  4. 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.

Optional features

New landing page

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:

  1. Create a new docs/source/index.rst file. Here you have a sample template ready to be adapted.

  2. Set "hide_sidebar_index": "false" in html_theme_options (conf.py).

New “Edit on GitHub” button

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.