ScyllaDB University Live | Free Virtual Training Event
Learn more
ScyllaDB Documentation Logo Documentation
  • Server
  • Cloud
  • Tools
    • ScyllaDB Manager
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
  • Resources
    • ScyllaDB University
    • Community Forum
    • Tutorials
Download
ScyllaDB Docs ScyllaDB Sphinx Theme Upgrade guides Migrating from 1.2 to 1.3

Caution

You're viewing documentation for a previous version of ScyllaDB Sphinx Theme. Switch to the latest stable version.

Migrating from 1.2 to 1.3¶

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

How to check your current theme version¶

The theme version is displayed in the footer of the project’s documentation site.

../_images/version.png

If your project theme’s version is >=1.2, follow this guide to get the latest version.

Upgrade to version 1.3¶

Here are the main breaking changes between the 1.2 and 1.3 versions.

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

    sphinx-scylladb-theme = "~1.3.1"
    redirects_cli ="~0.1.3"
    
  2. Add the new redirects command in docs/Makefile:

    .PHONY: redirects
    redirects: setup
        $(POETRY) run redirects-cli fromfile --yaml-file ./_utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml
        @echo
        @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
    
  3. Create a new file docs/_utils/redirects.yml. If the project has a file docs/_utils/redirections.yml, rename it to docs/_utils/redirects.yml and update it to the new format:

    Before, redirects were created for all versions:

    test-redirect: /stable/index
    

    If the project were building docs for the branches stable and branch-1.0, it would generate the following redirections:

    • /stable/test-redirect -> /stable/index

    • /branch-1.0/test-redirect -> /stable/index

    Now, you have more control to define redirects per version. To create the same redirects as in the previous example, the new format is:

    /stable/test-redirect.html: /stable/index.html
    /branch-1.0/test-redirect.html: /stable/index.html
    

    Note

    Notice that now you must append the .html extension to the redirects.

  4. Remove the file .github/workflows/docs-pages.yml. Then, copy the new workflow in the .github/workflows folder. You can download the latest docs-pages.yml workflow 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
    
  5. 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.3 or greater.

Optional features¶

Build previews only if the docs folder is updated¶

If the project is deploying docs pull request previews with AWS Ampify, you can update the configuration to improve the build time:

  1. Replace the amplify.yml in your root directory with the latest version.

  2. Follow the guide Build previews only if the docs folder is updated.

  3. Set the base image to build the docs to python:3.8 as described in Configure build settings.

Was this page helpful?

PREVIOUS
Migrating from 1.3 to 1.4
NEXT
Migrating from 1.1 to 1.2
  • Create an issue
  • Edit this page

On this page

  • Migrating from 1.2 to 1.3
    • How to check your current theme version
    • Upgrade to version 1.3
    • Optional features
      • Build previews only if the docs folder is updated
ScyllaDB Sphinx Theme
  • 1.4
    • 1.8
    • 1.7
    • 1.6
    • 1.5
    • 1.4
    • 1.3
    • 1.2
    • 1.1
  • Getting started
    • Toolchain
    • Installation
    • Quickstart
  • Configuration
    • Template options
    • Page options
    • Multiversion options
    • Markdown support
    • Redirects support
    • Search support
    • Troubleshooting
  • Commands
  • Deployment
    • Production deployment
    • Pull requests previews
  • Examples
    • Admonitions
    • Collapse
    • Code blocks
    • Glossary
    • Headings
    • Hero box
    • Includes
    • Images
    • Labels
    • Links
    • Lists
    • Panel box
    • Substitutions
    • Tables
    • Tabs
    • Text
    • TOC
    • Topic box
    • Versions
  • Upgrade guides
    • Migrating from 1.3 to 1.4
    • Migrating from 1.2 to 1.3
    • Migrating from 1.1 to 1.2
    • Migrating from 1.0 to 1.1
    • Migrating from 0.x to 1.0
    • Changelog
  • Contribute
    • Contribute to the documentation
    • Contribute to the theme
    • Source Code
Docs Tutorials University Contact Us About Us
© 2025 ScyllaDB | Terms of Service | Privacy Policy | ScyllaDB, and ScyllaDB Cloud, are registered trademarks of ScyllaDB, Inc.
Last updated on 01 Apr 2025.
Powered by Sphinx 7.4.7 & ScyllaDB Theme 1.8.6
Ask AI