Pallets Sphinx Themes

Sphinx themes for Pallets and related projects, providing consistent visual styling and specialized documentation directives for Flask, Jinja, Werkzeug, and Click projects. This package extends Sphinx with professionally designed themes and domain-specific directives for enhanced technical documentation.

Package Information

• Package Name: Pallets-Sphinx-Themes
• Package Type: pypi
• Language: Python
• Installation: pip install pallets-sphinx-themes

Core Imports

import pallets_sphinx_themes

For version utilities:

from pallets_sphinx_themes import get_version

Basic Usage

Add the extension to your Sphinx conf.py:

extensions = [
    "pallets_sphinx_themes",
    # ... other extensions
]

# Choose from available themes: flask, jinja, werkzeug, click, pocoo
html_theme = "flask"

Get version information for your project:

from pallets_sphinx_themes import get_version

release, version = get_version("MyProject")
# release = "1.0.3.dev0", version = "1.0.x"

Architecture

The package follows a modular architecture:

• Main Extension: Core Sphinx extension providing theme registration and configuration
• Theme System: Five themes (pocoo base theme + flask, jinja, werkzeug, click variants)
• Domain Extensions: Specialized Sphinx domains for Click and Jinja documentation
• Theme Detection: Automatic detection and configuration for Pallets-specific features
• Utility Functions: Version handling and project configuration helpers

All themes inherit from the base pocoo theme which provides consistent layout, styling, and documentation features across the Pallets ecosystem.

Capabilities

Core Extension Setup

Main Sphinx extension providing theme registration, configuration values, and integration with Sphinx's build system. Handles automatic theme detection and applies Pallets-specific enhancements.

def setup(app):
    """
    Register themes and configure Sphinx application.
    
    Parameters:
    - app: Sphinx application instance
    
    Returns:
    dict: Extension metadata with version and parallel_read_safe info
    """

Core Extension

Theme System

Five pre-configured Sphinx themes providing consistent visual styling for Pallets projects. Includes base pocoo theme and project-specific variants with custom stylesheets and Pygments syntax highlighting.

# Configuration values available in conf.py
is_pallets_theme: bool  # Auto-detected, indicates if using Pallets theme
rtd_canonical_path: str  # Canonical path for Read the Docs (default: "/en/stable/")
version_banner: bool  # Enable version warning banner (default: True)

Available themes: pocoo, flask, jinja, werkzeug, click

Theme System

Click Domain

Specialized Sphinx domain providing directives for documenting Click command-line applications. Enables interactive command examples with automatic input/output capture and syntax highlighting.

# Available directives in rst files
# .. click:example::
#    Python code defining Click commands
#
# .. click:run::
#    Commands to execute and display output

Click Domain

Jinja Domain

Specialized Sphinx domain for documenting Jinja2 templates, filters, tests, and node classes. Automatically generates comprehensive API documentation from Jinja mappings and class hierarchies.

# Available directives in rst files
# .. jinja:filters:: module.path.to.filters_dict
# .. jinja:tests:: module.path.to.tests_dict  
# .. jinja:nodes:: module.path.to.base_node_class

Jinja Domain

Utility Functions

Helper functions for version management and project configuration in Sphinx documentation projects.

def get_version(name: str, version_length: int = 2, placeholder: str = "x") -> tuple[str, str]:
    """
    Get version information for Sphinx documentation.
    
    Parameters:
    - name: Package name to get version for
    - version_length: Number of version components to include in short version
    - placeholder: Placeholder for additional version components
    
    Returns:
    tuple: (release, version) where release is full version, version is abbreviated
    """

Utilities

Configuration Values

The extension adds these configuration values to Sphinx:

# In conf.py
is_pallets_theme = None  # Auto-detected boolean, True if using Pallets theme
rtd_canonical_path = "/en/stable/"  # Canonical path for Read the Docs
version_banner = True  # Enable version warning banner

Theme Detection

The package automatically detects whether you're using a Pallets theme and enables appropriate features:

from pallets_sphinx_themes.theme_check import only_pallets_theme

@only_pallets_theme()
def my_pallets_specific_function(app):
    """Function only runs when using a Pallets theme."""
    pass

Types

from collections import namedtuple

ProjectLink = namedtuple("ProjectLink", ("title", "url"))
# Named tuple for project links with title and url fields