Migrating from 1.6 to 1.7¶

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.6, follow this guide to get the latest version.

Upgrade to version 1.7¶

Here are the main breaking changes between the 1.6 and 1.7 versions.

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

   sphinx-scylladb-theme = "~1.7.1"
   

2. To ensure documentation builds when backporting content to previous branches, update the .github/workflows/gh-pages.yml workflow file as outlined below:

   # (...)
   on:
     push:
       branches:
         - master # Replace with your default branch name
         - 'branch-**' # Use the versioned branch pattern
       paths:
         - "docs/**"
     workflow_dispatch:
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout
           uses: actions/checkout@v4
           with:
             ref: ${{ github.event.repository.default_branch }}
             persist-credentials: false
             fetch-depth: 0
         - name: Set up Python
           uses: actions/setup-python@v5
           with:
             python-version: '3.10'
   # (...)
   
   

3. The theme no longer supports Amplify. If your project includes the .github/actions/amplify-enhanced directory, the .github/workflows/docs-amplify-enhanced.yml workflow, or an amplify.yml file, consider removing them and move to the new approach. For more information, see Pull requests previews.

4. Build the docs locally:

   cd docs
   make preview
   

5. Review and address any warnings that may arise in the terminal during the build process.