Sphinx RTD Theme

A responsive and mobile-friendly Sphinx documentation theme designed primarily for Read the Docs but compatible with any Sphinx project. The theme combines Python packaging with JavaScript/CSS build tools to deliver a comprehensive documentation theme with excellent readability on both desktop and mobile devices.

Package Information

• Package Name: sphinx-rtd-theme
• Package Type: pypi
• Language: Python (with JavaScript components)
• Installation: pip install sphinx-rtd-theme

Core Imports

import sphinx_rtd_theme

For accessing theme configuration functions:

from sphinx_rtd_theme import get_html_theme_path, setup

Basic Usage

Theme Registration

Add to your Sphinx conf.py:

# Register theme (automatic via entry point)
html_theme = 'sphinx_rtd_theme'

# Optional theme options
html_theme_options = {
    'collapse_navigation': True,
    'sticky_navigation': True,
    'navigation_depth': 4,
    'includehidden': True,
    'titles_only': False
}

Manual Theme Setup (Advanced Usage)

import sphinx_rtd_theme

def setup(app):
    # Add theme path manually (not typically needed)
    app.add_html_theme('sphinx_rtd_theme', sphinx_rtd_theme.get_html_theme_path())
    
    # Theme is automatically registered via entry point:
    # sphinx.html_themes = sphinx_rtd_theme = sphinx_rtd_theme

Architecture

The theme consists of four main components:

• Python Extension: Sphinx theme registration, configuration validation, and template context extension
• HTML Templates: Complete Jinja2 template set for documentation rendering (layout, navigation, search, footer)
• JavaScript Navigation: Interactive ThemeNav class providing responsive navigation and mobile support
• Static Assets: CSS/SCSS styling and compiled JavaScript for responsive design

This modular architecture enables the theme to function as both a traditional Sphinx theme and a modern responsive web interface, with automatic jQuery integration, internationalization support, and Read the Docs environment detection.

Capabilities

Python Extension API

Core Sphinx extension functionality including theme registration, configuration validation with deprecation warnings, and template context extension for Read the Docs integration.

def setup(app): ...
def get_html_theme_path(): ...
def config_initiated(app, config): ...
def extend_html_context(app, pagename, templatename, context, doctree): ...

Python Extension

Theme Configuration

Comprehensive theme configuration system with 19 configurable options controlling navigation behavior, styling, and feature toggles including sticky navigation, collapsible menus, and responsive design settings.

# Theme options for html_theme_options in conf.py
{
    'collapse_navigation': bool,
    'sticky_navigation': bool,
    'navigation_depth': int,
    'includehidden': bool,
    'titles_only': bool,
    'logo_only': bool,
    'prev_next_buttons_location': str,
    'style_external_links': bool,
    'flyout_display': str,
    'version_selector': bool,
    'language_selector': bool
}

Theme Configuration

JavaScript Navigation API

Interactive navigation controller providing responsive behavior, mobile menu support, sticky navigation, and smooth scrolling with hash-based navigation state management.

class ThemeNav {
    enable(withStickyNav?: boolean): void;
    enableSticky(): void;
    init($: jQuery): void;
    reset(): void;
    toggleCurrent(elem: jQuery): void;
}

JavaScript Navigation

Build System Integration

Asset compilation and translation management system with webpack integration, custom setup.py commands, and npm script integration for theme development and distribution.

class WebpackBuildCommand: ...
class WebpackDevelopCommand: ...
class UpdateTranslationsCommand: ...
class TransifexCommand: ...

Build System

Package Metadata

__version__ = "3.0.2"
__version_full__ = "3.0.2"
logger = getLogger(__name__)

Dependencies

# Required dependencies
sphinx >=6,<9
docutils >0.18,<0.22
sphinxcontrib-jquery >=4,<5

# Development dependencies
transifex-client
bump2version
wheel
twine

Internationalization

Supports 21 languages with complete translation files:

• da, de, en, es, et, fa_IR, fr, hr, hu, it, lt, nl, pl, pt, pt_BR, ru, sv, tr, zh_CN, zh_TW