CrateDB Documentation Theme

0.50.3 verified Fri May 01 auth: no python

A Sphinx documentation theme for CrateDB documentation projects. Version 0.50.3, released monthly with minor improvements and dependency updates. Supports Sphinx 9.x and Python >=3.9.

pip install crate-docs-theme

Common errors

error Theme 'crate_docs_theme' not found ↓

cause Misspelled theme name or not installed.

fix

Ensure crate-docs-theme is installed: pip install crate-docs-theme. In conf.py, use exactly: html_theme = 'crate_docs_theme' (underscore, not hyphen).

error No module named 'sphinx_book_theme' ↓

cause Missing transitive dependency sphinx-book-theme.

fix

Install all dependencies: pip install crate-docs-theme sphinx-book-theme (or let pip resolve).

error Sphinx version 9.x incompatible ↓

cause Older crate-docs-theme did not support Sphinx 9.

fix

Upgrade to crate-docs-theme >=0.48.0 to support Sphinx 9.

Warnings

breaking The theme's TOC navigation behavior changed significantly between 0.44.0 and 0.46.0. If you rely on expand/collapse state persistence or custom TOC templates, review the changelog. ↓

fix Update to 0.46.0 or later for re-added TOC navigation with state persistence.

deprecated The 'crate_docs_theme' import path is the only correct one. Older versions may have used a different name; always use underscore. ↓

fix In conf.py, use: html_theme = 'crate_docs_theme'

gotcha The theme is built on top of sphinx-book-theme, which itself depends on pydata-sphinx-theme. Conflicts can arise if you mix custom CSS from other themes. ↓

fix Avoid overriding theme CSS unless you carefully inspect the stack.

gotcha When using the 'stepper' directive, the syntax changed in 0.48.0. Older documentation may reference the previous, more verbose syntax. ↓

fix Use the simplified stepper syntax introduced in 0.48.0.

Imports

html_theme

wrong

html_theme = 'crate-docs-theme'

correct

html_theme = 'crate_docs_theme'

Use underscore, not hyphen.

Quickstart

Basic Sphinx config to use crate-docs-theme.

# conf.py
import os

# Set the documentation theme
html_theme = 'crate_docs_theme'

# Optional: set project-specific config if needed
html_theme_options = {
    'repository_url': os.environ.get('REPO_URL', 'https://github.com/crate/crate'),
    'use_repository_button': True,
}