CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-pallets-sphinx-themes

Sphinx themes for Pallets and related projects with specialized documentation directives

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

theme-system.mddocs/

Theme System

Five pre-configured Sphinx themes providing consistent visual styling for Pallets projects. All themes inherit from the base pocoo theme and include project-specific stylesheets, Pygments syntax highlighting, and customized layouts.

Capabilities

Available Themes

Five themes are automatically registered when the extension loads, each designed for specific Pallets projects.

# Theme configuration in conf.py
html_theme = "pocoo"     # Base theme with pocoo styling
html_theme = "flask"     # Flask project theme  
html_theme = "jinja"     # Jinja project theme
html_theme = "werkzeug"  # Werkzeug project theme
html_theme = "click"     # Click project theme

Theme Detection

Automatic detection of whether the current theme is a Pallets theme, enabling theme-specific functionality.

def set_is_pallets_theme(app):
    """
    Set the is_pallets_theme config value based on current theme.
    
    Detects if the current theme inherits from the pocoo theme by
    checking theme directory hierarchy. Sets is_pallets_theme config
    to True/False accordingly.
    
    Parameters:
    - app: Sphinx application instance
    """

Theme-Specific Decorator

Decorator factory for creating functions that only execute when using a Pallets theme.

def only_pallets_theme(default=None):
    """
    Create decorator that executes function only with Pallets themes.
    
    Used to prevent Sphinx event callbacks from running when Pallets
    themes are installed but not active.
    
    Parameters:
    - default: Value to return if not using a Pallets theme
    
    Returns:
    function: Decorator that wraps the target function
    """

Theme Details

Pocoo Theme (Base)

The foundational theme that all other Pallets themes inherit from.

Configuration:

  • Inherits from: Sphinx basic theme
  • Stylesheet: pocoo.css
  • Pygments style: pocoo
  • Sidebars: localtoc.html, relations.html, searchbox.html, ethicalads.html
  • Options: index_sidebar_logo = True

Templates included:

  • layout.html - Main page layout
  • localtoc.html - Local table of contents
  • relations.html - Previous/next navigation
  • project.html - Project information
  • ethicalads.html - Ethical advertising integration

JavaScript:

  • describe_version.js - Version warning banner functionality

Flask Theme

Customized theme for Flask project documentation.

Configuration:

  • Inherits from: pocoo
  • Stylesheet: flask.css
  • Pygments style: Inherits from pocoo

Jinja Theme

Customized theme for Jinja project documentation with specialized syntax highlighting.

Configuration:

  • Inherits from: pocoo
  • Stylesheet: jinja.css
  • Pygments style: jinja (custom JinjaStyle class)

Click Theme

Customized theme for Click project documentation.

Configuration:

  • Inherits from: pocoo
  • Stylesheet: click.css
  • Pygments style: tango

Werkzeug Theme

Customized theme for Werkzeug project documentation.

Configuration:

  • Inherits from: pocoo
  • Stylesheet: werkzeug.css
  • Pygments style: Inherits from pocoo

Usage Examples

Basic Theme Selection

Configure your theme in conf.py:

# Select a theme
html_theme = "flask"

# Optional: Override theme-specific settings
html_theme_options = {
    "index_sidebar_logo": False  # For pocoo-based themes
}

Theme-Aware Functionality

Create functions that only run with Pallets themes:

from pallets_sphinx_themes.theme_check import only_pallets_theme

@only_pallets_theme()
def add_custom_css(app):
    """Add custom CSS only when using Pallets themes."""
    app.add_css_file("custom-pallets.css")

@only_pallets_theme(default="Not using Pallets theme")
def get_theme_status(app):
    """Return theme-specific message."""
    return f"Using Pallets theme: {app.builder.theme.name}"

def setup(app):
    app.connect("builder-inited", add_custom_css)

Conditional Configuration

Configure different behavior based on theme detection:

# conf.py
extensions = ["pallets_sphinx_themes"]
html_theme = "flask"

# This will be auto-set to True after theme detection
if html_theme in ["pocoo", "flask", "jinja", "werkzeug", "click"]:
    # Pallets-specific configuration
    version_banner = True
    rtd_canonical_path = "/en/stable/"
else:
    # Non-Pallets theme configuration
    version_banner = False

Pygments Style Configuration

The themes automatically set appropriate Pygments styles, but you can override:

# Automatic (recommended):
html_theme = "jinja"  # Automatically uses "jinja" pygments style
html_theme = "click"  # Automatically uses "tango" pygments style

# Manual override:
html_theme = "flask"
pygments_style = "pocoo"  # Override to use pocoo style instead

Configuration Values

Theme-related configuration values available in conf.py:

# Theme selection
html_theme = "flask"  # str: Theme name ("pocoo", "flask", "jinja", "werkzeug", "click")

# Auto-detected theme status (set by extension)
is_pallets_theme = None  # bool or None: True when using any Pallets theme

# Theme-specific options (pocoo base theme)
html_theme_options = {
    "index_sidebar_logo": True  # bool: Show logo in index sidebar
}

# Version banner (theme-aware)
version_banner = True  # bool: Enable version warning banner

# Canonical path for Read the Docs (theme-aware) 
rtd_canonical_path = "/en/stable/"  # str: Default canonical path

Install with Tessl CLI

npx tessl i tessl/pypi-pallets-sphinx-themes

docs

click-domain.md

core-extension.md

index.md

jinja-domain.md

theme-system.md

utilities.md

tile.json