Migrating from 0.x to 1.0¶

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:

   Note

   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 exists, 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
          @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¶