tessl/pypi-pydata-sphinx-theme

Bootstrap-based Sphinx theme from the PyData community

—

Pending

Overview

Eval results

Files

Template and Context Management

Name: tessl/pypi-pydata-sphinx-theme
Author: tessl

Template processing functionality that manages Jinja2 template rendering, asset injection, and HTML context preparation for each page during the Sphinx build process.

Capabilities

Template Processing

Updates template names and manages assets for each page during the build process.

def update_and_remove_templates(
    app: Sphinx, pagename: str, templatename: str, context, doctree
) -> None:
    """
    Update template names and assets for page build.
    
    This function processes templates for various theme sections:
    - Navigation bar sections (start, center, persistent, end)
    - Article header and footer sections  
    - Content footer items
    - Primary and secondary sidebar sections
    - Removes duplicate CSS files
    - Adds favicon links to page headers
    - Injects JavaScript variables for theme functionality
    
    Parameters:
    - app (Sphinx): Sphinx application instance
    - pagename (str): Name of the current page being processed
    - templatename (str): Name of the template being used
    - context: Template context dictionary with page variables
    - doctree: Document tree for the current page
    """

Canonical URL Fixing

Fixes canonical URLs when using Sphinx's directory HTML builder.

def _fix_canonical_url(
    app: Sphinx, pagename: str, templatename: str, context: dict, doctree
) -> None:
    """
    Fix the canonical URL when using the dirhtml builder.
    
    Sphinx builds incorrect canonical URLs ending with ".html" when using
    the dirhtml builder. This function detects and corrects the URL for
    each page.
    
    Parameters:
    - app (Sphinx): Sphinx application instance
    - pagename (str): Name of the current page
    - templatename (str): Template being used
    - context (dict): Page context with URL information
    - doctree: Document tree for the page
    """

Template Sections

The theme supports customizable template sections:

Navigation Bar Templates

theme_navbar_start: Left side of navigation bar
theme_navbar_center: Center of navigation bar
theme_navbar_persistent: Always visible navigation elements
theme_navbar_end: Right side of navigation bar

Article Templates

theme_article_header_start: Beginning of article header
theme_article_header_end: End of article header
theme_article_footer_items: Article footer elements

Content Templates

theme_content_footer_items: Content area footer elements

Footer Templates

theme_footer_start: Left side of page footer
theme_footer_center: Center of page footer
theme_footer_end: Right side of page footer

Sidebar Templates

theme_primary_sidebar_end: End of primary sidebar
sidebars: General sidebar configuration

Usage Examples

Custom Navigation Bar

# conf.py
html_theme_options = {
    "navbar_start": ["navbar-logo"],
    "navbar_center": ["navbar-nav", "search-field"],
    "navbar_end": ["navbar-icon-links"],
    "navbar_persistent": ["search-button"]
}

Custom Article Layout

# conf.py
html_theme_options = {
    "article_header_start": ["breadcrumbs"],
    "article_header_end": ["edit-this-page"],
    "article_footer_items": ["prev-next", "show-source"]
}

Sidebar Configuration

# conf.py  
html_theme_options = {
    "primary_sidebar_end": ["custom-sidebar.html"],
    "secondary_sidebar_items": ["page-toc", "edit-this-page"]
}

# Page-specific sidebar configuration
html_theme_options = {
    "secondary_sidebar_items": {
        "index": ["search-field"],
        "user-guide/**": ["page-toc", "edit-this-page"],
        "api/**": ["page-toc"]
    }
}

Favicon Configuration

# conf.py
html_theme_options = {
    "favicons": [
        {
            "rel": "icon",
            "sizes": "16x16", 
            "href": "favicon-16x16.png",
        },
        {
            "rel": "icon",
            "sizes": "32x32",
            "href": "favicon-32x32.png", 
        },
        {
            "rel": "apple-touch-icon",
            "sizes": "180x180",
            "href": "apple-touch-icon-180x180.png"
        },
        {
            "rel": "mask-icon",
            "href": "safari-pinned-tab.svg",
            "color": "#5bbad5"
        }
    ]
}

Theme Switcher Integration

# conf.py - Theme switcher with version matching
html_theme_options = {
    "switcher": {
        "json_url": "https://myproject.org/en/switcher.json", 
        "version_match": "v1.0.0"
    },
    "show_version_warning_banner": True
}

The switcher JSON format:

[
    {
        "name": "v1.0 (stable)",
        "version": "v1.0.0", 
        "url": "https://myproject.org/en/v1.0/"
    },
    {
        "name": "v1.1 (latest)",
        "version": "v1.1.0",
        "url": "https://myproject.org/en/latest/"
    }
]

Asset Management

The template system automatically:

Removes duplicate CSS files to prevent conflicts
Adds favicons with proper type and size attributes
Injects JavaScript variables for theme functionality
Manages version information for theme switcher
Handles theme-specific CSS and JavaScript assets

Context Variables

The template system injects several variables into the page context:

theme_version: Current theme version
pagename: Current page name for JavaScript
theme_switcher_*: Version switcher configuration
show_version_warning_banner: Whether to show version warnings
Theme-specific template lists for each customizable section

Install with Tessl CLI

npx tessl i tessl/pypi-pydata-sphinx-theme

docs

syntax-highlighting.md

template-management.md