custom.css

/* ================================================== */
/*                  ENHANCED DARK MODE CSS           */
/*                for Sphinx RTD Theme               */
/* ================================================== */

/* === DARK MODE COLOR SCHEME === */
/* Define all colors as CSS variables for easy maintenance and theming */
:root {
    /* Background colors - main dark theme palette */
    --dark-bg: #1c1c1c;              /* Primary dark background */
    --dark-bg-alt: #282828;          /* Secondary background for contrast */
    --dark-bg-hover: #333333;        /* Hover state background */
    --dark-bg-code: #171717;         /* Background for code blocks */
    
    /* Text colors - various shades for hierarchy */
    --light-text: #e0e0e0;           /* Primary light text color */
    --light-text-alt: #c0c0c0;       /* Secondary light text (slightly dimmer) */
    --dark-text: #1f1f1f;            /* Dark text for light backgrounds */
    --white-text: #ffffff;           /* Pure white text for contrast */
    --search-highlight-text: #333333; /* Dark text on highlighted backgrounds */
    
    /* Accent and interactive colors */
    --accent-blue: #40B4E8;          /* Primary blue accent for links */
    --highlight-yellow: #f1c40f;     /* Search term highlighting */
    --hover-gray: #404040;           /* Navigation hover background */
    --button-bg: #404040;            /* Navigation button background */
    --button-bg-hover: #505050;      /* Navigation button hover background */
    
    /* Heading colors */
    --heading-h1: #c0c0c0;           /* for main headings */
    --heading-h2: #969696;           /* for subheadings */
    --emphasis-gold: #439500;        /* for emphasized text */
    --code-teal: #20b2aa;            /* Light sea green for inline code */
    
    /* Navigation current page hierarchy - updated to match hard-coded values */
    --nav-current-light: #e3e3e3;    /* Light background for current items */
    --nav-current-l1: #404040;       /* Level 1 current page background */
    --nav-current-active: #525252;   /* Active current page link background */
    --nav-current-l2: #4d4d4d;       /* Level 2 current page background */
    --nav-current-l3: #595959;       /* Level 3 current page background */
    --nav-current-l4: #666666;       /* Level 4 current page background */
    --nav-current-l5: #737373;       /* Level 5 current page background */
    --nav-current-text: #d6d600;     /* Yellow text for current page links */
    
    /* Interface elements */  
    --border-dark: #555555;          /* Dark borders and dividers */
    --expand-button: #c2c2c2;        /* Tree expand button color */
    
    /* Table colors for alternating rows */
    --table-odd: #2e2e2e;            /* Odd table row background */
    --table-even: #262626;           /* Even table row background */
    
    /* Admonition (note/warning) accent colors */
    --warning-orange: #f39c12;       /* Orange for warning admonitions */
    --danger-red: #e74c3c;           /* Red for danger/error admonitions */
    
    /* Print mode colors */
    --print-bg: #ffffff;             /* White background for printing */
    --print-text: #000000;           /* Black text for printing */
}

/* === LAYOUT OVERRIDES === */
/* Increase content width beyond RTD theme default while keeping code blocks reasonable */
.wy-nav-content {
    max-width: 1000px !important;
}

/* === BODY AND MAIN CONTENT === */
/* Set the primary dark background and text color for the entire page */
body {
    background-color: var(--dark-bg) !important;
    color: var(--light-text) !important;
}

/* Ensure content areas inherit the dark background */
.wy-nav-content,
.wy-nav-content-wrap {
    background-color: var(--dark-bg);
}

/* === SIDEBAR AND NAVIGATION === */
/* Style the top navigation and search areas with dark theme */
.wy-side-nav-search, 
.wy-nav-top {
    background: var(--dark-bg-alt) !important;
    border-color: var(--border-dark) !important;
}

/* Base navigation menu styling - remove borders and set text colors */
.wy-menu-vertical a {
    color: var(--light-text) !important;
    border: none;
    padding: 1.4045em 1.618em;
}
l1
/* Top-level navigation links use slightly dimmer text */
.wy-menu-vertical li.toctree-l1 > a {
    color: var(--light-text-alt)!important;
}

/* Nested navigation levels use dark text (appears on lighter backgrounds) */
.wy-menu-vertical li.toctree-l2 > a,
.wy-menu-vertical li.toctree-l3 > a,
.wy-menu-vertical li.toctree-l4 > a,
.wy-menu-vertical li.toctree-l5 > a {
    color: var(--light-text) !important;
}

/* Navigation hover effects - unified styling for all navigation levels */
/* Provides consistent white text on gray background for all hover states */
.wy-menu-vertical a:hover,
.wy-nav-side .wy-menu-vertical li.toctree-l2 a:hover,
.wy-nav-side .wy-menu-vertical li.toctree-l3 a:hover,
.wy-nav-side .wy-menu-vertical li.toctree-l4 a:hover,
.wy-nav-side .wy-menu-vertical li.toctree-l5 a:hover,
.wy-nav-side .wy-menu-vertical li.current ul li a:hover,
.wy-nav-side .wy-menu-vertical ul li a:hover {
    color: var(--white-text) !important;
    background-color: var(--hover-gray) !important;
}

/* Current page styling - visual hierarchy for active navigation */
/* Base current page background (light gray) */
.wy-menu-vertical li.current {
    background: var(--nav-current-light)!important;
}

/* Current page link gets hover-style background */
.wy-menu-vertical li.current > a {
    background: var(--dark-bg-hover) !important;
}

/* Active current page links - gray background with yellow text for visibility */
.wy-menu-vertical li.toctree-l1.current > a {
    background: var(--nav-current-l1) !important;
    color: var(--nav-current-text) !important
}
.wy-menu-vertical li.toctree-l2.current > a {
    background: var(--nav-current-l2) !important;
    color: var(--nav-current-text) !important
}
.wy-menu-vertical li.toctree-l3.current > a {
    background: var(--nav-current-l3) !important;
    color: var(--nav-current-text) !important
}
.wy-menu-vertical li.toctree-l4.current,
.wy-menu-vertical li.toctree-l4.current > a {
    background: var(--nav-current-l4) !important;
    color: var(--nav-current-text) !important
}
.wy-menu-vertical li.toctree-l5.current,
.wy-menu-vertical li.toctree-l5.current > a {
    background: var(--nav-current-l5) !important;
    color: var(--nav-current-text) !important;
}

/* Level 2 current page specific styling */
.wy-menu-vertical li.toctree-l3 > a {
    background: var(--nav-current-l3) !important;
}

/* Level 3 current page specific styling */
.wy-menu-vertical li.toctree-l2 > a,
.wy-menu-vertical li.toctree-l4 > a {
    background: var(--nav-current-l3) !important;
}

/* Tree expand/collapse button styling */
button.toctree-expand {
    color: var(--expand-button) !important;
}

.wy-menu-vertical li.current a {
    border: none;
    padding: 1.4045em 2.427em;
}

/* === PREVIOUS/NEXT NAVIGATION BUTTONS === */
/* Style both top and bottom navigation buttons to match dark theme */
.rst-footer-buttons {
    margin: 3em 0;
}

/* Previous and Next button styling - comprehensive selectors for all locations */
.btn-neutral,
.rst-footer-buttons .btn-neutral,
.rst-footer-buttons a.btn-neutral,
.rst-content .btn-neutral,
.rst-content a.btn-neutral,
div[role="navigation"] .btn-neutral,
div[role="navigation"] a.btn-neutral {
    background-color: var(--button-bg) !important;
    color: #ffffff !important;
    border: 1px solid var(--border-dark) !important;
    border-radius: 4px;
    padding: 10px 20px;
    text-decoration: none;
}

/* Button hover effects */
.btn-neutral:hover,
.rst-footer-buttons .btn-neutral:hover,
.rst-footer-buttons a.btn-neutral:hover,
.rst-content .btn-neutral:hover,
.rst-content a.btn-neutral:hover,
div[role="navigation"] .btn-neutral:hover,
div[role="navigation"] a.btn-neutral:hover {
    background-color: var(--button-bg-hover) !important;
    color: #ffffff !important;
    border-color: var(--accent-blue) !important;
}

/* Button focus states for accessibility */
.btn-neutral:focus,
.rst-footer-buttons .btn-neutral:focus,
.rst-footer-buttons a.btn-neutral:focus,
.rst-content .btn-neutral:focus,
.rst-content a.btn-neutral:focus,
div[role="navigation"] .btn-neutral:focus,
div[role="navigation"] a.btn-neutral:focus {
    background-color: var(--button-bg-hover) !important;
    color: #ffffff !important;
    border-color: var(--accent-blue) !important;
    outline: 2px solid var(--accent-blue);
    outline-offset: 2px;
}

/* Icon styling within buttons */
.btn-neutral .fa,
.rst-footer-buttons .btn-neutral .fa,
.rst-footer-buttons a.btn-neutral .fa,
.rst-content .btn-neutral .fa,
.rst-content a.btn-neutral .fa,
div[role="navigation"] .btn-neutral .fa,
div[role="navigation"] a.btn-neutral .fa {
    color: #ffffff !important;
}

/* Additional button variants if they exist */
.btn {
    background-color: var(--button-bg) !important;
    color: var(--white-text) !important;
    border: 1px solid var(--border-dark) !important;
}

.btn:hover {
    background-color: var(--button-bg-hover) !important;
    color: var(--white-text) !important;
    border-color: var(--accent-blue) !important;
}

/* === HEADINGS === */
/* Main page headings - blue for primary hierarchy */
h1 {
    color: var(--heading-h1) !important;
}

/* Subheadings - green for secondary hierarchy */
h2 {
    color: var(--heading-h2) !important;
}

/* === LINKS === */
/* Standard link styling - blue accent color for all link states */
a, 
a:link, 
a:visited {
    color: var(--accent-blue);
}

/* Link hover state - white text for better contrast */
a:hover {
    color: var(--white-text);
}

/* === TEXT FORMATTING === */
/* Bold/emphasized text (**text** in markdown) - gold color for emphasis */
strong {
    color: var(--emphasis-gold)!important; 
    font-weight: 700;
}

/* === CODE BLOCKS === */
/* Inline code styling (`code` in markdown) - teal text with dark background */
code.docutils.literal {
    color: var(--code-teal);
    background-color: var(--dark-bg-hover)!important;
    border: 1px solid var(--border-dark)!important;
    padding: 2px 4px;
    border-radius: 3px;
}

/* Fix RTD theme inline code that breaks table formatting */
.rst-content code.literal,
.rst-content tt.literal {
    white-space: nowrap !important;
}

/* Multi-line code blocks with syntax highlighting */
div.highlight pre {
    background-color: var(--dark-bg-code) !important;
    color: var(--light-text);
    border: 1px solid var(--border-dark);
    overflow-x: auto; /* Enable horizontal scrolling for long lines */
    min-width: 700px;
    width: fit-content; /* Auto-size to content width */
    max-width: 100%; /* Prevent code blocks from exceeding container */
    box-sizing: border-box; /* Include padding and borders in width calculation */
}

/* Code block containers - prevent full-width expansion */
div.highlight,
.rst-content div[class^="highlight"] {
    width: fit-content; /* Auto-size container to content */
    max-width: 100%;
    overflow-x: auto;
    margin: 1em 0;
}

/* === TABLES === */
/* Fix RTD responsive table wrapper that causes first table text wrapping */
.wy-table-responsive {
    overflow: visible !important;
    max-width: none !important;
}

/* Table headers - dark background with white text for contrast */
table.docutils th,
table th,
.rst-content table.docutils th {
    background-color: var(--dark-bg) !important;
    color: var(--white-text) !important;
    border: 1px solid var(--border-dark) !important;
    padding: 8px 12px !important;
}


/* Table cells - inherit colors from parent rows */
table.docutils td,
table td,
.rst-content table.docutils td {
    background-color: inherit !important;
    color: inherit !important;
    border: 1px solid var(--border-dark) !important;
    padding: 8px 12px !important;
    white-space: nowrap !important; /* Prevent text wrapping in cells */
}

/* Base table styling */
table.docutils,
table,
.rst-content table.docutils {
    border-collapse: collapse !important;
    border: 1px solid var(--border-dark) !important;
    width: auto; /* Auto-size to content instead of 100% */
    margin: 1em 0;
}

/* Alternating table row colors for improved readability */
/* Support multiple row class naming conventions */
.row-odd,
tr:nth-child(odd),
table.docutils tbody tr:nth-child(odd),
.rst-content table.docutils tbody tr:nth-child(odd) {
    background: var(--table-odd) !important;
    color: var(--light-text) !important;
}

.row-even,
tr:nth-child(even),
table.docutils tbody tr:nth-child(even),
.rst-content table.docutils tbody tr:nth-child(even) {
    background: var(--table-even) !important;
    color: var(--light-text-alt) !important;
}

/* Table hover effects for better UX */
table.docutils tbody tr:hover,
.rst-content table.docutils tbody tr:hover {
    background-color: var(--dark-bg-hover) !important;
    color: var(--white-text) !important;
}

/* === ADMONITIONS (Notes, Warnings, etc.) === */
/* Base styling for all admonition boxes (.. note::, .. warning::, etc.) */
div.admonition {
    background-color: var(--dark-bg-alt)!important;
    border-color: var(--border-dark) !important;
    color: var(--light-text) !important;
}

/* Ensure admonition text remains readable */
div.admonition p {
    color: var(--light-text)!important;
}

/* Specific admonition types with colored left borders for visual distinction */
/* Note admonitions - blue accent border */
div.admonition.note {
    border-left: 4px solid var(--accent-blue)!important;
}

/* Warning admonitions - orange border */
div.admonition.warning {
    border-left: 4px solid var(--warning-orange);
}

/* Danger/error admonitions - red border */
div.admonition.danger {
    border-left: 4px solid var(--danger-red)!important;
}

/* === SEARCH HIGHLIGHTING === */
/* Enhanced search term highlighting - works with search-phrase.js */
/* Yellow background with dark text and subtle glow effect */
span.highlighted,
.rst-content .highlighted,
.wy-nav-content-wrap .highlighted,
article .highlighted {
    background-color: var(--highlight-yellow) !important;
    color: var(--search-highlight-text) !important;
    box-shadow: 0 0 0 2px var(--highlight-yellow);
    font-weight: 700;
    padding: 1px 2px;
    border-radius: 2px;
}

/* === FORMS AND INPUTS === */
/* Search input and form fields with dark theme styling */
input[type="text"],
input[type="search"] {
    background-color: var(--dark-bg-alt)!important;
    color: var(--light-text)!important;
    border: 1px solid var(--border-dark)!important;
}

/* Input focus states - brighter background and blue border */
input[type="text"]:focus,
input[type="search"]:focus {
    background-color: var(--dark-bg-hover)!important;
    border-color: var(--accent-blue)!important;
}

/* === RESPONSIVE IMPROVEMENTS === */
/* Mobile-friendly padding adjustments for smaller screens */
@media (max-width: 768px) {
    .wy-nav-content {
        padding: 1.618em 1em;
    }
}

/* === ACCESSIBILITY IMPROVEMENTS === */
/* Custom text selection highlighting - blue background with white text */
::selection {
    background-color: var(--accent-blue)!important;
    color: var(--white-text)!important;
}

/* === SCROLLBAR STYLING === */
/* Custom scrollbar to match dark theme */
/* Webkit browsers (Chrome, Safari, Edge) */
::-webkit-scrollbar {
    width: 12px;
    height: 12px;
}

::-webkit-scrollbar-track {
    background: var(--dark-bg-alt)!important;
    border-radius: 6px;
}

::-webkit-scrollbar-thumb {
    background: var(--border-dark)!important;
    border-radius: 6px;
    border: 2px solid var(--dark-bg-alt)!important;
}

::-webkit-scrollbar-thumb:hover {
    background: var(--hover-gray)!important;
}

::-webkit-scrollbar-corner {
    background: var(--dark-bg-alt)!important;
}

/* Firefox scrollbar styling */
html {
    scrollbar-width: thin;
    scrollbar-color: var(--border-dark) var(--dark-bg-alt);
}

/* === PRINT STYLES === */
/* Print-friendly styling - revert to standard black text on white background */
@media print {
    body {
        background: var(--print-bg) !important;
        color: var(--print-text) !important;
    }
}