ScyllaDB University Live | Free Virtual Training Event
Learn more
ScyllaDB Documentation Logo Documentation
  • Server
    • ScyllaDB Open Source
    • ScyllaDB Enterprise
    • ScyllaDB Alternator
  • Cloud
  • Tools
    • ScyllaDB Manager
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu
ScyllaDB Docs ScyllaDB Sphinx Theme Upgrade guides Migrating from 1.0 to 1.1

Migrating from 1.0 to 1.1¶

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

Changes in custom landing pages¶

If you were using the Custom landing page feature:

  1. Add the following lines at the top of the file docs/source/index.rst:

    :full-width:
    :hide-version-warning:
    :hide-pre-content:
    :hide-post-content:
    :landing:
    
  2. Remove the lines:

    .. raw:: html
    
    <div class="landing landing--floating">
    

    Note

    Remember to delete its closing </div> tag. Here is the complete diff.

PREVIOUS
Migrating from 1.1 to 1.2
NEXT
Migrating from 0.x to 1.0
ScyllaDB Sphinx Theme
  • 1.4
    • 1.4
    • 1.3
    • 1.2
    • 1.1
    • 1.0
  • 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
  • Create an issue
  • Edit this page

On this page

  • Migrating from 1.0 to 1.1
    • How to check your current theme version
    • Upgrade to version 1.1
    • Optional features
      • Changes in custom landing pages
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon Forum Icon
© 2023, ScyllaDB. All rights reserved.
Last updated on 14 Mar 2023.
Powered by Sphinx 4.5.0 & ScyllaDB Theme 1.4.1