Registry / web-framework / sphinx-rtd-dark-mode

sphinx-rtd-dark-mode

library1.3.0pypypiunverified

sphinx-rtd-dark-mode is a Sphinx extension that adds a toggleable dark mode to the Read the Docs Sphinx theme. Currently at version 1.3.0, it receives periodic updates to enhance styling, fix visual bugs across various Sphinx elements, and improve user experience.

web-framework

pip install sphinx-rtd-dark-mode

github ↗package ↗

INSTALL

IMPORT

SIG · SPHINX-RTD-DARK-MO

sphinx-rtd-dark-mode

web-frameworkpythonv1.3.0

Install

6.6s avg

Import

—

Disk

104MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 102.5MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 6.6s · import 0.000s · 103MB

104MB installed

● package 104MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sphinx_rtd_dark_mode

✓ extensions = ['sphinx_rtd_dark_mode']

✗ import sphinx_rtd_dark_mode

Sphinx extensions are activated by adding their module name to the 'extensions' list in conf.py, not via direct Python imports.

To enable sphinx-rtd-dark-mode, first ensure you have `sphinx` and `sphinx-rtd-theme` installed. Then, add `'sphinx_rtd_dark_mode'` to the `extensions` list in your `conf.py` file. Optionally, set `default_dark_mode = False` if you prefer the light theme on the first load.

# conf.py import os import sys # Add your project's path if necessary # sys.path.insert(0, os.path.abspath('.')) project = 'My Project' copyright = '2026, Your Name' author = 'Your Name' version = '0.1' release = '0.1.0' html_theme = 'sphinx_rtd_theme' extensions = [ 'sphinx_rtd_dark_mode', ] # Optional: Set the default mode (True for dark, False for light) default_dark_mode = True # To build: # sphinx-build -b html . _build

Debug

Known issues

gotchaThis extension is exclusively designed for the 'sphinx_rtd_theme'. If you have a different `html_theme` set in `conf.py`, the extension will override it to `sphinx_rtd_theme` to function correctly.

fix

Ensure `html_theme = 'sphinx_rtd_theme'` is set, or be aware the extension will set it for you.

affects: All versions

gotchaThe `default_dark_mode` configuration option (boolean) controls whether users see dark mode or light mode on their *first* visit to the documentation. If not explicitly set, the default is `True` (dark mode first). User preferences are stored in local storage thereafter.

fix

Set `default_dark_mode = False` in `conf.py` if you prefer users to start in light mode.

affects: All versions

breakingOlder versions (prior to 1.0.1 and 1.1.1) had issues with static CSS files not being included during installation, leading to the dark mode not appearing or being partially broken.

fix

Upgrade to version 1.1.1 or later (`pip install --upgrade sphinx-rtd-dark-mode`).

affects: <1.0.1, <1.1.1

gotchaVarious styling issues, such as unreadable text on certain elements (e.g., `guilabel`, admonitions, code blocks, navigation, tables) or incorrect fonts, were present in older versions.

fix

Ensure you are using the latest version (1.3.0+) for the most comprehensive styling fixes: `pip install --upgrade sphinx-rtd-dark-mode`.

affects: <1.3.0

Upgrade

Version history

1.3.0latest on PyPI · released Sep 19, 2023

Audit

Dependencies

sphinxrequiredCore documentation generator

sphinx-rtd-themerequiredThis extension is designed specifically for and requires the Read the Docs Sphinx theme. It will automatically set this theme if not already configured.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/MrDogeBro/sphinx_rtd_dark_mode ↗

packagehttps://pypi.org/project/sphinx-rtd-dark-mode/ ↗