Configuration and Theming

def update_mode_thebe_config(app):
    """
    Update Thebe configuration with sphinx-book-theme specific values.
    
    Automatically configures Thebe when launch_buttons.thebe is enabled:
    - Sets repository_url if not already configured
    - Sets repository_branch (defaults to 'master' if not specified)
    - Warns if sphinx_thebe extension is not installed
    
    Parameters:
    - app: Sphinx application instance (thebe_config modified in-place)
    """

def check_deprecation_keys(app):
    """
    Check for and warn about deprecated configuration keys.
    
    Currently checks for:
    - 'single_page': Deprecated since version 0.3.4
    
    Issues warnings with links to changelog for deprecated options.
    
    Parameters:
    - app: Sphinx application instance
    """

def update_general_config(app, config):
    """
    Update general Sphinx configuration for the theme.
    
    Adds theme template paths to Sphinx configuration:
    - Adds theme/components directory to templates_path
    
    Parameters:
    - app: Sphinx application instance
    - config: Sphinx configuration object (modified in-place)
    """

# Translation constants
MESSAGE_CATALOG_NAME: str = "booktheme"  # Catalog identifier

# Translation setup is handled in setup() function:
# - Adds message catalog from theme/static/locales
# - Provides translation context in page rendering

# In Sphinx conf.py
extensions = ['sphinx_thebe']  # Required for Thebe support

html_theme_options = {
    "repository_url": "https://github.com/user/repo",
    "repository_branch": "main",
    "launch_buttons": {
        "thebe": True
    }
}

# Optional custom Thebe configuration
thebe_config = {
    "repository_url": "https://github.com/user/repo",
    "repository_branch": "main", 
    "repository_provider": "github",
    "selector": ".cell",
    "kernel_name": "python3"
}

# Configuration that triggers deprecation warning
html_theme_options = {
    "single_page": True,  # Will generate warning
    "use_download_button": True  # Valid option
}

# Warning output:
# WARNING: 'single_page' was deprecated from version 0.3.4 onwards.
# See the CHANGELOG for more information: 
# https://github.com/executablebooks/sphinx-book-theme/blob/master/CHANGELOG.md

from sphinx_book_theme import check_deprecation_keys, update_general_config

def setup(app):
    # Check for deprecated options during builder initialization
    app.connect("builder-inited", check_deprecation_keys)
    
    # Update configuration
    update_general_config(app, app.config)
    
    return {"parallel_read_safe": True}

from sphinx_book_theme import update_mode_thebe_config
from pydata_sphinx_theme.utils import get_theme_options_dict

def custom_thebe_setup(app):
    # Configure theme options first
    theme_options = get_theme_options_dict(app)
    theme_options["launch_buttons"] = {"thebe": True}
    theme_options["repository_url"] = "https://github.com/user/repo"
    
    # Update Thebe configuration
    update_mode_thebe_config(app)
    
    # Check resulting configuration
    if hasattr(app.env.config, 'thebe_config'):
        thebe_config = app.env.config.thebe_config
        print(f"Thebe repository: {thebe_config.get('repository_url')}")
        print(f"Thebe branch: {thebe_config.get('repository_branch')}")

from sphinx.locale import get_translation

# Get translation function (done automatically in page context)
translation = get_translation("booktheme")

# Use in templates or code
translated_text = translation("Download this page")
search_placeholder = translation("Search") + "..."

html_theme_options = {
    # Launch buttons
    "launch_buttons": {
        "thebe": True,
        "binderhub_url": "https://mybinder.org",
        "jupyterhub_url": "https://hub.example.com",
        "colab_url": "https://colab.research.google.com",
        "notebook_interface": "jupyterlab"  # or "classic"
    },
    
    # Repository configuration  
    "repository_url": "https://github.com/user/repo",
    "repository_branch": "main",
    "repository_provider": "github",  # auto-detected if not specified
    "path_to_docs": "docs",
    
    # Button toggles
    "use_download_button": True,
    "use_fullscreen_button": True, 
    "use_repository_button": True,
    "use_source_button": True,
    "use_edit_page_button": True,
    "use_issues_button": True,
    
    # Content features
    "use_sidenotes": True,
    
    # Footer customization
    "theme_footer_content_items": ["copyright", "sphinx-version"],
    
    # Search
    "search_bar_text": "Search documentation..."
}

# Additional Thebe configuration
thebe_config = {
    "repository_url": "https://github.com/user/repo",
    "repository_branch": "main",
    "repository_provider": "github",
    "selector": "div.highlight",  # Elements to make executable
    "kernel_name": "python3",
    "request_kernel_on_load": False,
    "pre_render_hook": "function() { console.log('Pre-render'); }",
    "mount_hook": "function() { console.log('Mounted'); }"
}

def setup(app):
    # Configuration events
    app.connect("builder-inited", update_mode_thebe_config)
    app.connect("builder-inited", check_deprecation_keys) 
    app.connect("config-inited", update_general_config)
    
    return {"parallel_read_safe": True}