HTML Post-Processing

def changed_docs(app: Sphinx, env: BuildEnvironment, docnames: list[str]) -> None:
    """
    Add a list of changed docs to the environment.
    
    This is useful to make sure postprocessing only runs on changed files,
    improving build performance by avoiding unnecessary HTML modifications.
    
    Parameters:
    - app (Sphinx): The Sphinx application instance
    - env (BuildEnvironment): The Sphinx build environment
    - docnames (list[str]): List of document names that have changed
    """

def get_html_files(outdir: pathlib.Path | str) -> list[str]:
    """
    Get a list of HTML files in the output directory.
    
    Recursively searches the output directory for all files with .html extension.
    
    Parameters:
    - outdir (pathlib.Path | str): Output directory to search
    
    Returns:
    list[str]: List of HTML file paths
    """

def post_process_html(app: Sphinx, exc: Exception | None) -> None:
    """
    Modify the HTML after building.
    
    Makes changes that are easier to do in the final HTML rather than
    the tree of nodes. Only processes files that have changed.
    
    Parameters:
    - app (Sphinx): The Sphinx application instance
    - exc (Exception | None): Build exception if any occurred
    """

def modify_html(html_filename: str, app: Sphinx) -> None:
    """
    Modify a single HTML document.
    
    1. Parse the HTML document into a BeautifulSoup tree
    2. Apply modifications in order and in place
    3. Write the modified HTML back to the file
    
    Parameters:
    - html_filename (str): Path to the HTML file to modify
    - app (Sphinx): The Sphinx application instance
    """

def collapsible_nav(tree: BeautifulSoup) -> None:
    """
    Make navigation links with children collapsible.
    
    Adds Alpine.js directives for interactive behavior:
    - x-data for state management
    - @click for toggle behavior
    - x-show for visibility control
    - :class for dynamic styling
    
    Parameters:
    - tree (BeautifulSoup): The parsed HTML document tree
    """

def headerlinks(tree: BeautifulSoup) -> None:
    """
    Make headerlinks copy their URL on click.
    
    Adds Alpine.js click handler that:
    - Copies the link URL to clipboard
    - Shows "Copied!" feedback message
    - Resets to original message after 2 seconds
    
    Parameters:
    - tree (BeautifulSoup): The parsed HTML document tree
    """

def scrollspy(tree: BeautifulSoup) -> None:
    """
    Add an active class to current TOC links in the right sidebar.
    
    Uses Alpine.js intersection observer to:
    - Track which section is currently visible
    - Update activeSection variable
    - Apply data-current attribute to matching TOC links
    
    Parameters:
    - tree (BeautifulSoup): The parsed HTML document tree
    """

def external_links(tree: BeautifulSoup) -> None:
    """
    Add rel="nofollow noopener" to external links and append icons.
    
    Enhances security by:
    - Adding rel attributes to prevent page hijacking
    - Appending visual icons to identify external links
    
    Parameters:
    - tree (BeautifulSoup): The parsed HTML document tree
    """

def remove_empty_toctree(tree: BeautifulSoup) -> None:
    """
    Remove empty toctree divs.
    
    If you include a toctree with the hidden option, an empty div is
    inserted. This function removes these empty divs that contain only
    whitespace characters.
    
    Parameters:
    - tree (BeautifulSoup): The parsed HTML document tree
    """

def strip_comments(tree: BeautifulSoup) -> None:
    """
    Remove HTML comments from documents.
    
    Cleans up the final HTML by removing all HTML comment nodes,
    reducing file size and eliminating unnecessary markup.
    
    Parameters:
    - tree (BeautifulSoup): The parsed HTML document tree
    """

@dataclass(frozen=True)
class Icons:
    """Icons from Material Design as SVG strings."""
    
    external_link: str = '<svg xmlns="http://www.w3.org/2000/svg"...'>
    """External link icon SVG"""
    
    chevron_right: str = '<svg xmlns="http://www.w3.org/2000/svg"...'>
    """Right chevron icon for navigation"""
    
    permalinks_icon: str = '<svg xmlns="http://www.w3.org/2000/svg"...'>
    """Permalink icon for header links"""

html_theme_options = {
    "awesome_external_links": True,    # Enable external link enhancement
    "awesome_headerlinks": True,       # Enable header link clipboard copy
}

<!-- Navigation state management -->
<li x-data="{ expanded: $el.classList.contains('current') ? true : false }">
    <a @click="expanded = !expanded" :class="{ 'expanded' : expanded }">...</a>
    <ul x-show="expanded">...</ul>
</li>

<!-- Scroll spy tracking -->
<h2 x-intersect.margin.0%.0%.-70%.0%="activeSection = '#section-id'">...</h2>
<a :data-current="activeSection === '#section-id'">...</a>

<!-- Clipboard copy -->
<a @click.prevent="navigator.clipboard.writeText($el.href)">...</a>