Qiskit Sphinx Theme

2.0.0 verified Fri May 01 auth: no python

A Sphinx theme for Qiskit and Qiskit Ecosystem projects, currently at version 2.0.0. Provides a consistent look and feel for Qiskit documentation. Releases follow Qiskit's release cadence.

pip install qiskit-sphinx-theme

Common errors

error Theme 'qiskit_sphinx_theme' not found ↓

cause The theme is not installed or the name is misspelled (e.g., used hyphen instead of underscore).

fix

Install correctly: pip install qiskit-sphinx-theme, and in conf.py use html_theme = 'qiskit_sphinx_theme'

error WARNING: html_theme option 'qiskit-sphinx-theme' is not a valid theme name ↓

cause Using hyphen in theme name in conf.py, but Sphinx expects underscore.

fix

Change html_theme = 'qiskit_sphinx_theme'

Warnings

breaking Version 2.0.0 dropped support for Sphinx < 4.0. If you are using an older Sphinx, upgrade Sphinx first. ↓

fix Upgrade Sphinx: pip install 'sphinx>=4.0'

gotcha The theme name in conf.py must use underscores (qiskit_sphinx_theme) not hyphens. ↓

fix Set html_theme = 'qiskit_sphinx_theme'

Imports

QiskitSphinxTheme
wrong
```
import qiskit_sphinx_theme
```
correct
```
from qiskit_sphinx_theme import __version__
```
Direct import of the module is fine, but to get version use __version__

html_theme

wrong

html_theme = 'qiskit-sphinx-theme'

correct

html_theme = 'qiskit_sphinx_theme'

Use underscore, not hyphen, in conf.py

Quickstart

Basic Sphinx configuration using qiskit-sphinx-theme as the HTML theme.

# conf.py
import os

project = 'My Qiskit Project'
# ... other settings

html_theme = 'qiskit_sphinx_theme'
html_theme_options = {
    'logo_only': False,
    'display_version': True,
}

# Ensure the extension is loaded
# extensions list may include qiskit_sphinx_theme if needed