Core Extension

def setup(app):
    """
    Register Pallets themes and configure Sphinx application.
    
    Automatically discovers and registers all themes in the themes directory,
    adds configuration values, configures sphinx-notfound-page extension,
    and connects event handlers for theme-specific functionality.
    
    Parameters:
    - app: Sphinx application instance
    
    Returns:
    dict: Extension metadata containing version and parallel_read_safe status
    """

def find_base_canonical_url(app):
    """
    Configure canonical URL from Read the Docs environment.
    
    When building on Read the Docs, constructs the base canonical URL from
    environment variables if not explicitly configured. Only active when
    using a Pallets theme.
    
    Parameters:
    - app: Sphinx application instance
    """

def add_theme_files(app):
    """
    Add theme-specific JavaScript files and version banners.
    
    Conditionally includes version warning JavaScript based on build
    environment and configuration. Only active when using a Pallets theme.
    
    Parameters:
    - app: Sphinx application instance
    """

def canonical_url(app, pagename, templatename, context, doctree):
    """
    Fix canonical URLs for dirhtml builder.
    
    Corrects canonical URL generation when using Sphinx's dirhtml builder
    to avoid incorrect .html suffixes. Only active when using a Pallets theme.
    
    Parameters:
    - app: Sphinx application instance
    - pagename: Name of the page being processed
    - templatename: Template being used
    - context: Template context dictionary
    - doctree: Document tree being processed
    """

def skip_internal(app, what, name, obj, skip, options):
    """
    Skip autodoc rendering for internal-only objects.
    
    Skips rendering when an object's docstring contains a line with only
    the string ':internal:'. Only active when using a Pallets theme.
    
    Parameters:
    - app: Sphinx application instance
    - what: Type of object being documented
    - name: Name of the object
    - obj: The object itself
    - skip: Current skip status
    - options: Autodoc options
    
    Returns:
    bool or None: True to skip, None to use default behavior
    """

def cut_module_meta(app, what, name, obj, options, lines):
    """
    Remove copyright and license lines from module documentation.
    
    Filters out lines starting with ':copyright:' or ':license:' from
    module autodoc to reduce noise in generated documentation.
    Only active when using a Pallets theme.
    
    Parameters:
    - app: Sphinx application instance
    - what: Type of object being documented
    - name: Name of the object
    - obj: The object itself
    - options: Autodoc options
    - lines: List of docstring lines (modified in place)
    """

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

# Select a theme
html_theme = "flask"  # or "jinja", "werkzeug", "click", "pocoo"

# Optional: Configure canonical path for Read the Docs
rtd_canonical_path = "/en/latest/"

# Optional: Disable version banner
version_banner = False

from pallets_sphinx_themes.theme_check import only_pallets_theme

@only_pallets_theme()
def my_custom_handler(app):
    """Custom handler that only runs with Pallets themes."""
    # Your custom functionality here
    pass

def setup(app):
    app.connect("builder-inited", my_custom_handler)

# Automatic configuration (when extension loads):
app.config.extensions.append("notfound.extension")
app.config.notfound_context = {
    "title": "Page Not Found", 
    "body": "The page you requested does not exist..."
}

# Outside Read the Docs, disables URL prefix:
if "READTHEDOCS" not in os.environ:
    app.config.notfound_urls_prefix = None

# Theme detection (auto-set, can be overridden)
is_pallets_theme = None  # bool or None

# Read the Docs canonical path
rtd_canonical_path = "/en/stable/"  # str

# Version banner control  
version_banner = True  # bool