Migrating from 1.0 to 1.1¶

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.1¶

Here are the main breaking changes between the 1.0 and 1.1 versions.

1. Install Poetry 1.12 or later on your computer.

2. Update the following Python dependencies in docs/pyproject.toml:

   [tool.poetry.dependencies]
   python = "^3.7"
   pyyaml = "^6.0"
   pygments = "^2.11.2"
   recommonmark = "^0.7.1"
   sphinx-scylladb-theme = "~1.1.0"
   sphinx-sitemap = "^2.1.0"
   sphinx-autobuild = "^2021.3.14"
   Sphinx = "^4.3.2"
   sphinx-multiversion-scylla = "~0.2.10"
   

3. In conf.py, remove the option "hide_sidebar_index": "true" (if exists).

   Note

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

4. Edit docs/Makefile:

   1. Replace:

      POETRY = $(HOME)/.poetry/bin/poetry
      

      With:

      POETRY = $(HOME)/.local/bin/poetry
      

   2. Replace:

      .PHONY: setup
      setup:
          ./_utils/setup.sh
      

      With:

      .PHONY: setup
      setup:
          $(POETRY) install
          $(POETRY) update
      

5. Remove the file docs/_utils/setup.sh.

6. Remove the files .github/workflows/docs-*.yml. Then, copy the new workflows in the .github/workflows folder. You can download the latest workflows here.

   If the default branch is not master or the docs are not under the docs folder, the workflows to match the project configuration. For example:

   on:
   push:
       branches:
       - master # edit this line
       paths:
       - "docs/**" # edit this line
   

7. 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.1 or greater.

Optional features¶