Header Buttons System

def prep_header_buttons(app, pagename, templatename, context, doctree):
    """
    Initialize empty header buttons list in page context.
    
    Sets up context["header_buttons"] = [] for other functions to populate.
    
    Parameters:
    - app: Sphinx application instance
    - pagename: Name of the page being processed
    - templatename: Template being used
    - context: Template context (modified to include header_buttons list)
    - doctree: Document tree for the page
    """

def add_header_buttons(app, pagename, templatename, context, doctree):
    """
    Add general header buttons including download and fullscreen buttons.
    
    Adds buttons for:
    - Download source file (.rst, .md, .ipynb)
    - Download as PDF (print to PDF)
    - Fullscreen mode toggle
    
    Parameters:
    - app: Sphinx application instance
    - pagename: Name of the page being processed  
    - templatename: Template being used
    - context: Template context with header_buttons list
    - doctree: Document tree for the page
    """

def add_launch_buttons(app: Sphinx, pagename: str, templatename: str, 
                      context: dict[str, Any], doctree: Optional[document]):
    """
    Add launch buttons for interactive online environments.
    
    Supports:
    - Binder (BinderHub instances)
    - JupyterHub 
    - Google Colab
    - Deepnote
    - Thebe (live code execution)
    
    Parameters:
    - app: Sphinx application instance
    - pagename: Name of the page being processed
    - templatename: Template being used
    - context: Template context with header_buttons and launch configuration
    - doctree: Document tree (optional, None for HTML-only pages)
    """

def add_source_buttons(app, pagename, templatename, context, doctree):
    """
    Add source repository navigation buttons.
    
    Provides buttons for:
    - Repository home page
    - View source file online
    - Edit page (suggest edit)  
    - Open issue/bug report
    
    Supports GitHub, GitLab, and Bitbucket.
    
    Parameters:
    - app: Sphinx application instance
    - pagename: Name of the page being processed
    - templatename: Template being used  
    - context: Template context with repository configuration
    - doctree: Document tree for the page
    """

def update_context_with_repository_info(app):
    """
    Update Sphinx context with repository information from theme options.
    
    Extracts repository URL, branch, and provider information from
    theme configuration and populates html_context for use by
    pydata-sphinx-theme functions.
    
    Parameters:
    - app: Sphinx application instance (config modified in-place)
    """

def update_sourcename(app):
    """
    Configure source file suffix for download links.
    
    Sets html_sourcelink_suffix to empty string unless explicitly
    configured, ensuring native file extensions (.rst, .md) are used
    instead of Sphinx's default .txt.
    
    Parameters:
    - app: Sphinx application instance (config modified in-place)
    """

def as_bool(var) -> bool:
    """
    Convert various inputs to boolean values.
    
    Handles string 'true'/'false', boolean values, and None.
    
    Parameters:
    - var: Value to convert (str, bool, or None)
    
    Returns:
    Boolean representation of the input
    """

def get_repo_parts(context) -> tuple:
    """
    Extract repository components from page context.
    
    Parameters:
    - context: Page template context
    
    Returns:
    Tuple of (provider_url, user, repo, provider) or None if not found
    """

def get_repo_url(context) -> tuple[str, str]:
    """
    Get complete repository URL and provider from context.
    
    Parameters:
    - context: Page template context
    
    Returns:
    Tuple of (repository_url, provider_name)
    """

def _split_repo_url(url) -> tuple:
    """
    Split a repository URL into an org/repo combination.
    
    Currently supports GitHub URLs, with warnings for other providers.
    
    Parameters:
    - url: Repository URL string
    
    Returns:
    Tuple of (org, repo) or (None, None) if not supported
    """

def _is_notebook(app, context) -> bool:
    """
    Determine if the current page is a notebook.
    
    Checks for 'kernelspec' in metadata or '.ipynb' in page source suffix.
    
    Parameters:
    - app: Sphinx application instance
    - context: Page template context
    
    Returns:
    True if the page is a notebook, False otherwise
    """

def _get_branch(config_theme) -> str:
    """
    Get repository branch from theme configuration.
    
    Parameters:
    - config_theme: Theme configuration dictionary
    
    Returns:
    Branch name (defaults to 'master' if not specified)
    """

# Launch module constants
SPHINX_LOGGER: Logger  # Logger instance for launch button functionality
MESSAGE_CATALOG_NAME: str = "booktheme"  # Translation catalog name

# Header buttons module constants  
LOGGER: Logger  # Logger instance for general header button functionality

from sphinx_book_theme.header_buttons import prep_header_buttons, add_header_buttons

# In Sphinx conf.py
html_theme_options = {
    "use_download_button": True,
    "use_fullscreen_button": True,
}

# Buttons are automatically added via event handlers:
# app.connect("html-page-context", prep_header_buttons)
# app.connect("html-page-context", add_header_buttons, priority=501)

# In Sphinx conf.py  
html_theme_options = {
    "repository_url": "https://github.com/user/repo",
    "repository_branch": "main",
    "launch_buttons": {
        "binderhub_url": "https://mybinder.org",
        "jupyterhub_url": "https://hub.example.com", 
        "colab_url": "https://colab.research.google.com",
        "thebe": True,
        "notebook_interface": "jupyterlab"  # or "classic"
    }
}

# In Sphinx conf.py
html_theme_options = {
    "repository_url": "https://github.com/user/repo",
    "use_repository_button": True,
    "use_source_button": True, 
    "use_edit_page_button": True,
    "use_issues_button": True,
    "path_to_docs": "docs"  # relative path to docs in repo
}

from sphinx_book_theme.header_buttons import add_launch_buttons

def custom_page_handler(app, pagename, templatename, context, doctree):
    # Ensure header_buttons exists
    if "header_buttons" not in context:
        context["header_buttons"] = []
    
    # Add launch buttons if this is a notebook page
    add_launch_buttons(app, pagename, templatename, context, doctree)
    
    # Add custom button
    context["header_buttons"].append({
        "type": "link",
        "url": "https://example.com",
        "text": "Custom Link", 
        "tooltip": "Custom tooltip",
        "icon": "fas fa-external-link-alt"
    })

from sphinx_book_theme.header_buttons import get_repo_parts, get_repo_url

# Extract repository information
context = {
    "github_url": "https://github.com",
    "github_user": "executablebooks", 
    "github_repo": "sphinx-book-theme"
}

# Get repository parts
provider_url, user, repo, provider = get_repo_parts(context)
# Returns: ("https://github.com", "executablebooks", "sphinx-book-theme", "github")

# Get full repository URL
repo_url, provider = get_repo_url(context)  
# Returns: ("https://github.com/executablebooks/sphinx-book-theme", "github")