HTML Translation

class BootstrapHTML5TranslatorMixin:
    """
    Mixin HTML Translator for a Bootstrap-ified Sphinx layout.
    
    Modifies Sphinx's default HTML output to produce valid HTML that can be
    directly styled with Bootstrap, while fulfilling accessibility best practices.
    Only overrides specific functions needed for Bootstrap compatibility.
    
    This mixin is combined with Sphinx's existing translators to retain all
    original functionality while adding Bootstrap-specific enhancements.
    """
    
    def __init__(self, *args, **kwds):
        """
        Initialize the translator with Bootstrap table styling.
        
        Sets default table style to 'table' for Bootstrap compatibility.
        
        Parameters:
        - *args: Arguments passed to parent translator
        - **kwds: Keyword arguments passed to parent translator
        """
    
    def starttag(self, *args, **kwargs):
        """
        Perform small modifications to tags.
        
        Ensures accessibility compliance by:
        - Setting aria-level for any tag with heading role
        - Maintaining all original starttag functionality
        
        Parameters:
        - *args: Arguments for tag creation
        - **kwargs: Tag attributes and options
        
        Returns:
        str: HTML start tag with Bootstrap and accessibility enhancements
        """
    
    def visit_table(self, node):
        """
        Custom visit table method.
        
        Creates Bootstrap-compatible tables by:
        - Adding 'table' class instead of 'docutils' and 'align-default'
        - Supporting autosummary tables with special styling
        - Adding responsive table wrapper for horizontal scrolling
        - Preserving width and alignment attributes
        
        Parameters:
        - node: Table node being processed
        """
    
    def depart_table(self, node):
        """
        Custom depart_table method to close the scrollable div.
        
        Properly closes the scrollable container div added in visit_table
        while maintaining parent functionality.
        
        Parameters:
        - node: Table node being processed
        """

def setup_translators(app: Sphinx):
    """
    Add bootstrap HTML functionality if we are using an HTML translator.
    
    Dynamically creates new translator classes that combine the Bootstrap
    mixin with existing Sphinx translators. This preserves all original
    translator behavior while adding Bootstrap-specific enhancements.
    
    The function:
    - Detects existing HTML translators
    - Creates new classes combining Bootstrap mixin with original translators
    - Registers the enhanced translators with Sphinx
    - Skips non-HTML builders to avoid conflicts
    
    Parameters:
    - app (Sphinx): Sphinx application instance
    """

<!-- Standard Sphinx table -->
<table class="docutils align-default">
    <thead>...</thead>
    <tbody>...</tbody>
</table>

<!-- Bootstrap-enhanced table -->
<div class="pst-scrollable-table-container">
    <table class="table">
        <thead>...</thead>
        <tbody>...</tbody>
    </table>
</div>

.. table:: Aligned Table
   :align: center

   ======  ======
   Header  Header  
   ======  ======
   Data    Data
   ======  ======

<div class="pst-scrollable-table-container">
    <table class="table table-center">
        <!-- table content -->
    </table>
</div>

.pst-scrollable-table-container {
    overflow-x: auto;
    -webkit-overflow-scrolling: touch;
}

<!-- Automatic aria-level addition -->
<div role="heading" aria-level="2">Section Title</div>

# When sphinx.ext.autosummary generates API tables
# The translator adds 'autosummary' class automatically

<div class="pst-scrollable-table-container">
    <table class="table autosummary">
        <!-- API documentation table -->
    </table>
</div>

Simple Table
============

======  ======  ======
Col 1   Col 2   Col 3
======  ======  ======
Data    Data    Data
More    More    More
======  ======  ======

Wide Data Table
===============

===========  ===========  ===========  ===========  ===========
Parameter    Type         Default      Description  Example
===========  ===========  ===========  ===========  ===========
width        int          800          Table width  1200
height       int          600          Table height 900
responsive   bool         True         Enable wrap  False
===========  ===========  ===========  ===========  ===========

.. table:: Custom Styled Table
   :widths: 30 70
   :width: 100%

   ==========  ====================================
   Feature     Description
   ==========  ====================================
   Bootstrap   Automatic Bootstrap 5 styling
   Responsive  Mobile-friendly horizontal scroll
   Accessible  ARIA attributes and semantic HTML
   ==========  ====================================

/* Bootstrap table styling is automatically applied */
.table {
    width: 100%;
    margin-bottom: 1rem;
    color: var(--bs-body-color);
    vertical-align: top;
    border-color: var(--bs-border-color);
}

/* Theme-specific table enhancements */
.pst-scrollable-table-container {
    overflow-x: auto;
    margin-bottom: 1rem;
}

.table.autosummary {
    font-size: 0.9em;
}

.table.autosummary td {
    white-space: nowrap;
}

# conf.py - Disable Bootstrap table enhancement
# (Advanced: requires custom theme modification)
def setup(app):
    # Custom setup without Bootstrap translator
    pass

# conf.py - Custom table styling
html_theme_options = {
    "custom_css": "custom-tables.css"
}

/* custom-tables.css */
.table {
    border-collapse: separate;
    border-spacing: 0;
}

.table thead th {
    border-bottom: 2px solid var(--pst-color-primary);
}

.table.autosummary {
    font-family: 'Monaco', 'Menlo', monospace;
}