Syntax Highlighting

def get_pygments_stylesheet(light_style: str, dark_style: str) -> str:
    """
    Generate the theme-specific pygments.css.
    
    Creates a CSS stylesheet that includes both light and dark syntax
    highlighting styles with appropriate CSS selectors for theme switching.
    Sphinx normally only supports one pygments style, but this function
    enables dynamic switching between light and dark styles.
    
    Parameters:
    - light_style (str): Pygments style name for light theme
    - dark_style (str): Pygments style name for dark theme
    
    Returns:
    str: Complete CSS stylesheet with both light and dark styles
    """

def _get_styles(formatter: HtmlFormatter, prefix: str) -> None:
    """
    Get styles out of a formatter, where everything has the correct prefix.
    
    Extracts CSS styles from a Pygments formatter and applies the specified
    CSS prefix to enable theme-specific styling.
    
    Parameters:
    - formatter (HtmlFormatter): Pygments HTML formatter instance
    - prefix (str): CSS selector prefix to apply
    
    Yields:
    str: CSS rules with proper prefixes applied
    """

def overwrite_pygments_css(app: Sphinx, exception=None):
    """
    Overwrite pygments.css to allow dynamic light/dark switching.
    
    Sphinx natively supports pygments_style and pygments_dark_style but only
    uses CSS media queries. This function replaces the generated CSS with
    JavaScript-controlled theme switching using data attributes.
    
    The function:
    - Validates and applies fallbacks for unavailable styles
    - Generates CSS with theme-specific prefixes
    - Writes the combined stylesheet to _static/pygments.css
    
    Parameters:
    - app (Sphinx): Sphinx application instance
    - exception: Build exception (function exits early if present)
    """

# conf.py
html_theme_options = {
    "pygments_light_style": "github-light",
    "pygments_dark_style": "github-dark"
}

# conf.py - Custom style configuration
html_theme_options = {
    "pygments_light_style": "tango",
    "pygments_dark_style": "native", 
    "surface_warnings": True  # Show warnings for missing styles
}

# Fallback to Sphinx's default configuration
pygments_style = "default"         # Used if theme style not found
pygments_dark_style = "monokai"    # Used if theme dark style not found

# GitHub-inspired
html_theme_options = {
    "pygments_light_style": "github-light",
    "pygments_dark_style": "github-dark"
}

# Solarized theme
html_theme_options = {
    "pygments_light_style": "solarized-light", 
    "pygments_dark_style": "solarized-dark"
}

# High contrast
html_theme_options = {
    "pygments_light_style": "default",
    "pygments_dark_style": "native"
}

# Colorful options
html_theme_options = {
    "pygments_light_style": "colorful",
    "pygments_dark_style": "monokai"
}

# conf.py - Custom Pygments configuration
html_theme_options = {
    "pygments_light_style": "custom-light",
    "pygments_dark_style": "custom-dark"
}

# You can also define custom styles by subclassing Pygments styles
from pygments.styles.default import DefaultStyle
from pygments.token import Keyword, Name, Comment, String, Error, Generic

class CustomLightStyle(DefaultStyle):
    styles = {
        Comment: '#008000',
        Keyword: '#0000ff',
        Name: '#000080',
        String: '#ba2121',
        Error: 'border:#ff0000'
    }

# conf.py - Use standard Sphinx Pygments (no theme switching)
# Don't set pygments_*_style in theme options
# Use standard Sphinx configuration instead:
pygments_style = "default"
pygments_dark_style = "monokai"  # CSS media query based

/* Light theme styles */
html[data-theme="light"] .highlight .hll { background-color: #ffffcc }
html[data-theme="light"] .highlight .c { color: #008000 }
html[data-theme="light"] .highlight .k { color: #0000ff }

/* Dark theme styles */  
html[data-theme="dark"] .highlight .hll { background-color: #49483e }
html[data-theme="dark"] .highlight .c { color: #75715e }
html[data-theme="dark"] .highlight .k { color: #66d9ef }

.. code-block:: python
   
   def hello_world():
       print("Hello, world!")

.. literalinclude:: example.py
   :language: python
   :lines: 1-10

```python
# Direct code blocks also supported
def example():
    return "formatted code"