Migrating from 1.2 to 1.3¶

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