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 0.x to 1.0

Caution

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

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.

../_images/version.png

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¶

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 can find 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.

Was this page helpful?

PREVIOUS
Migrating from 1.0 to 1.1
NEXT
Changelog
  • Create an issue
  • Edit this page

On this page

  • Migrating from 0.x to 1.0
    • How to check your current theme version
    • Upgrade to version 1.0
    • Optional features
      • New landing page
      • New “Edit on GitHub” button
ScyllaDB Sphinx Theme
  • 1.2
    • 1.8
    • 1.7
    • 1.6
    • 1.5
    • 1.4
    • 1.3
    • 1.2
    • 1.1
  • Getting started
    • Toolchain
    • Installation
  • Configuration
    • Template options
    • Page options
    • Multiversion options
    • Markdown support
    • Redirections support
    • Search support
    • Troubleshooting
  • Commands
  • Deployment
    • Production deployment
    • Pull requests previews
  • Examples
    • Admonitions
    • Collapse
    • Code blocks
    • Glossary
    • Headings
    • Hero box
    • Includes
    • Images
    • Links
    • Lists
    • Panel box
    • Substitutions
    • Tables
    • Tabs
    • Text
    • TOC
    • Topic box
    • Versions
  • Upgrade guides
    • 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