tessl/pypi-sphinx-book-theme

A clean book theme for scientific explanations and documentation with Sphinx

Overview

Eval results

Files

Core Theme Setup

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

Main Sphinx extension setup and theme path functionality. This module provides the primary entry points for registering the sphinx-book-theme with Sphinx applications.

Capabilities

Theme Registration

The main setup function that registers the theme with Sphinx, adds assets, configures event handlers, and sets up all theme functionality.

def setup(app: Sphinx) -> dict:
    """
    Register the sphinx-book-theme with a Sphinx application.
    
    This function:
    - Registers the HTML theme
    - Adds JavaScript and CSS files
    - Sets up message catalog for internationalization
    - Connects event handlers for page processing
    - Registers custom nodes and directives
    - Configures post-transforms
    
    Parameters:
    - app: Sphinx application instance
    
    Returns:
    dict with extension metadata including parallel read/write safety
    """

Theme Path Resolution

Gets the filesystem path to the theme's HTML templates and static assets.

def get_html_theme_path() -> Path:
    """
    Return the path to the HTML theme directory.
    
    Returns:
    Path to the theme directory containing templates and static assets
    """

Module Constants

__version__: str = "1.1.4"  # Package version
SPHINX_LOGGER: Logger  # Logger instance for theme messages
DEFAULT_LOG_TYPE: str = "sphinxbooktheme"  # Default log type
MESSAGE_CATALOG_NAME: str = "booktheme"  # Internationalization catalog name

Usage Examples

Basic Theme Registration

from sphinx.application import Sphinx
import sphinx_book_theme

# Create Sphinx application
app = Sphinx(...)

# Register the theme
result = sphinx_book_theme.setup(app)
# Returns: {"parallel_read_safe": True, "parallel_write_safe": True}

Getting Theme Assets Path

from sphinx_book_theme import get_html_theme_path

# Get path to theme directory
theme_path = get_html_theme_path()
print(theme_path)  # /path/to/sphinx_book_theme/theme/sphinx_book_theme

# Access static assets
static_path = theme_path / "static"
templates_path = theme_path / "components"

Version Information

import sphinx_book_theme

print(f"Theme version: {sphinx_book_theme.__version__}")
# Output: Theme version: 1.1.4

Install with Tessl CLI

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

docs