Quickstart

This guide walks you through installing and enabling Clarity Theme for Sphinx so you can start building fast, attractive documentation with the Sphinx static site generator.

Obtaining the theme

The theme is dual-licensed under the free MIT or Commercial License. For commercial use, the Commercial License is recommended. It offers bonus assets, no attribution requirements, and priority support.

Consider purchasing a license at https://readcraft.io/sphinx-clarity-theme to fund the development 🙏

Installation

Install the theme file using your preferred Python package manager like pip or uv. Theme files and dependencies are placed where Sphinx can automatically find them.

1. Add the theme package as a dependency to virtual environment or Python project where do you manage Sphinx itself.

   Using pip

   For pip, the most common package installer:

   pip install sphinx_clarity_theme
   

   Using uv

   For uv, a fast Python package manager:

   Option 1: Add to existing project (if you have pyproject.toml, it adds it as dependency to it):

   uv add sphinx_clarity_theme
   

   Option 2: Install to active environment (doesn’t modify or require pyproject.toml):

   uv pip install sphinx_clarity_theme
   

Configuration

Configure the theme in your Sphinx conf.py.

1. Enable the theme.

   html_theme = "sphinx_clarity_theme"
   

2. (Optional) Most visual and behavioral customization lives in html_theme_options; some items (like html_favicon) use standard Sphinx variables.

   html_favicon = "favicon.svg"
   html_theme_options = {
      # See later for customization options
   }
   

Rebuild your docs and you should see Clarity Theme for Sphinx applied.

Theme options

To configure theme, you use the html_theme_options in conf.py, which is a plain dictionary.

html_theme_options = {
    "logo_dark": "_static/logo-dark.svg",
    "logo_url": "https://readcraft.io",
    ...
}

However, for code auto-completion in IDE and typos prevention when editing, you can use the ThemeOptions type.

from sphinx_clarity_theme import ThemeOptions

...

html_theme_options: ThemeOptions = {
    "logo_dark": "_static/logo-dark.svg",
    "logo_url": "https://readcraft.io",
    ...
}