Utilities

def get_version(name, version_length=2, placeholder="x"):
    """
    Get version information for Sphinx documentation.
    
    Ensures the named package is installed and returns properly formatted
    version strings for use in Sphinx conf.py. Creates both a full release
    version and an abbreviated version suitable for documentation display.
    
    Parameters:
    - name (str): Name of package to get version information for
    - version_length (int): Number of version components to include in abbreviated version (default: 2)  
    - placeholder (str): Placeholder suffix for abbreviated version (default: "x")
    
    Returns:
    tuple[str, str]: (release, version) where:
        - release: Full version string (e.g., "1.0.3.dev0")  
        - version: Abbreviated version (e.g., "1.0.x")
    
    Raises:
    SystemExit: If the specified package is not installed
    """

def set_is_pallets_theme(app):
    """
    Detect and configure Pallets theme usage.
    
    Examines the current Sphinx theme to determine if it inherits from
    the pocoo theme, setting the is_pallets_theme configuration value
    accordingly. This enables conditional theme-specific functionality.
    
    Parameters:
    - app: Sphinx application instance
    """

def only_pallets_theme(default=None):
    """
    Create decorator for theme-conditional functions.
    
    Returns a decorator that ensures the wrapped function only executes
    when using a Pallets theme. Used to prevent Sphinx event callbacks
    from running when Pallets themes are installed but not active.
    
    Parameters:
    - default: Value to return if not using a Pallets theme (default: None)
    
    Returns:
    function: Decorator that wraps target functions with theme checking
    """

ProjectLink = namedtuple("ProjectLink", ("title", "url"))
"""
Named tuple for project links.

Fields:
- title (str): Display title for the link
- url (str): URL target for the link

Used for rendering consistent project links in Sphinx themes.
"""

# conf.py
from pallets_sphinx_themes import get_version

# Get version for your project
release, version = get_version("MyProject")
# release = "2.1.3.dev0", version = "2.1.x"

# Custom version formatting
release, version = get_version("MyProject", version_length=3, placeholder="dev")
# release = "2.1.3.dev0", version = "2.1.3.dev"

# Single component version
release, version = get_version("MyProject", version_length=1, placeholder="")
# release = "2.1.3.dev0", version = "2"

from pallets_sphinx_themes.theme_check import only_pallets_theme

@only_pallets_theme()
def setup_pallets_features(app):
    """Configure features specific to Pallets themes."""
    app.add_css_file("pallets-custom.css")
    app.config.html_show_sourcelink = False

@only_pallets_theme(default="Generic theme in use")
def get_theme_message(app):
    """Get theme-specific message."""
    return f"Using Pallets theme: {app.builder.theme.name}"

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

from pallets_sphinx_themes import ProjectLink

# Create project links
docs_link = ProjectLink("Documentation", "https://example.com/docs")
github_link = ProjectLink("Source Code", "https://github.com/user/project")

# Use in templates or configuration
project_links = [docs_link, github_link]

# Access fields
print(f"Visit {docs_link.title} at {docs_link.url}")

try:
    from pallets_sphinx_themes import get_version
    release, version = get_version("MyOptionalDependency")
except SystemExit:
    # Package not installed, use fallback
    release = "unknown"
    version = "dev"
    print("Warning: MyOptionalDependency not found, using fallback version")

from pallets_sphinx_themes.theme_check import only_pallets_theme

@only_pallets_theme()
def add_version_info(app, pagename, templatename, context, doctree):
    """Add version information to page context."""
    if app.config.project:
        try:
            release, version = get_version(app.config.project)
            context['project_release'] = release
            context['project_version'] = version
        except SystemExit:
            context['project_release'] = "unknown"
            context['project_version'] = "dev"

def setup(app):
    app.connect("html-page-context", add_version_info)

# conf.py
extensions = ["pallets_sphinx_themes"]

# After extension loads, is_pallets_theme will be set
def setup(app):
    @only_pallets_theme()
    def load_pallets_extensions(app):
        """Load additional extensions for Pallets themes."""
        if "sphinx_design" not in app.config.extensions:
            app.config.extensions.append("sphinx_design")
        if "sphinx_copybutton" not in app.config.extensions:
            app.config.extensions.append("sphinx_copybutton")
    
    app.connect("builder-inited", load_pallets_extensions)

# Example version strings for different inputs:

# Package version: "1.2.3"
get_version("pkg")           # ("1.2.3", "1.2.x")
get_version("pkg", 1)        # ("1.2.3", "1.x") 
get_version("pkg", 3)        # ("1.2.3", "1.2.3.x")
get_version("pkg", 2, "dev") # ("1.2.3", "1.2.dev")

# Package version: "2.0.1.post1"  
get_version("pkg")           # ("2.0.1.post1", "2.0.x")
get_version("pkg", 3)        # ("2.0.1.post1", "2.0.1.x")

# Package version: "1.0.0a1"
get_version("pkg")           # ("1.0.0a1", "1.0.x")
get_version("pkg", 3, "")    # ("1.0.0a1", "1.0.0")